@c -----------------------------------------------------------------------------
@node Functional Categories, Alphabetical List, Introduction, Top
@unnumbered Functional Categories

@menu
* bios functions::
* conio functions::
* cpu functions::
* ctype functions::
* debugging functions::
* dos functions::
* dpmi functions::
* environment functions::
* file system functions::
* go32 functions::
* io functions::
* locale functions::
* math functions::
* memory functions::
* misc functions::
* mono functions::
* posix functions::
* process functions::
* profiling functions::
* random number functions::
* search functions::
* shell functions::
* signal functions::
* sound functions::
* startup functions::
* stdio functions::
* string functions::
* sys functions::
* termios functions::
* time functions::
* unistd functions::
* unix functions::
@end menu
@c -----------------------------------------------------------------------------
@node bios functions, conio functions, , Functional Categories
@unnumberedsec bios functions
@menu
* _bios_disk::
* _bios_equiplist::
* _bios_keybrd::
* _bios_memsize::
* _bios_printer::
* _bios_serialcom::
* _bios_timeofday::
* bioscom::
* biosdisk::
* biosequip::
* bioskey::
* biosmemory::
* biosprint::
* biostime::
* __get_extended_key_string::
* getkey::
* getxkey::
* kbhit::
@end menu
@c -----------------------------------------------------------------------------
@node conio functions, cpu functions, bios functions, Functional Categories
@unnumberedsec conio functions
@menu
* blinkvideo::
* cgets::
* clreol::
* clrscr::
* _conio_gettext::
* _conio_kbhit::
* cprintf::
* cputs::
* cscanf::
* delline::
* getch::
* getche::
* gettext::
* gettextinfo::
* gotoxy::
* gppconio_init::
* highvideo::
* insline::
* intensevideo::
* lowvideo::
* movetext::
* normvideo::
* putch::
* puttext::
* Screen Variables::
* ScreenClear::
* ScreenCols::
* ScreenGetChar::
* ScreenGetCursor::
* ScreenMode::
* ScreenPutChar::
* ScreenPutString::
* ScreenRetrieve::
* ScreenRows::
* ScreenSetCursor::
* ScreenUpdate::
* ScreenUpdateLine::
* ScreenVisualBell::
* _set_screen_lines::
* _setcursortype::
* textattr::
* textbackground::
* textcolor::
* textmode::
* ungetch::
* wherex::
* wherey::
* window::
@end menu
@c -----------------------------------------------------------------------------
@node cpu functions, ctype functions, conio functions, Functional Categories
@unnumberedsec cpu functions
@menu
* _8087::
* _clear87::
* _control87::
* _detect_80387::
* disable::
* enable::
* _fpreset::
* htonl::
* htons::
* inb::
* inp::
* inportb::
* inportl::
* inportsb::
* inportsl::
* inportsw::
* inportw::
* inpw::
* _my_cs::
* _my_ds::
* _my_ss::
* ntohl::
* ntohs::
* outb::
* outp::
* outportb::
* outportl::
* outportsb::
* outportsl::
* outportsw::
* outportw::
* outpw::
* _status87::
@end menu
@c -----------------------------------------------------------------------------
@node ctype functions, debugging functions, cpu functions, Functional Categories
@unnumberedsec ctype functions
@menu
* isalnum::
* isalpha::
* isascii::
* isblank::
* iscntrl::
* isdigit::
* isgraph::
* islower::
* isprint::
* ispunct::
* isspace::
* isupper::
* isxdigit::
* toascii::
* _tolower::
* tolower::
* _toupper::
* toupper::
@end menu
@c -----------------------------------------------------------------------------
@node debugging functions, dos functions, ctype functions, Functional Categories
@unnumberedsec debugging functions
@menu
* cleanup_client::
* edi_init::
* load_npx::
* read_child::
* read_sel_addr::
* redir_cmdline_delete::
* redir_cmdline_parse::
* redir_debug_init::
* redir_to_child::
* redir_to_debugger::
* run_child::
* save_npx::
* syms_init::
* syms_line2val::
* syms_listwild::
* syms_module::
* syms_name2val::
* syms_val2line::
* syms_val2name::
* v2loadimage::
* wild::
* write_child::
* write_sel_addr::
@end menu
@c -----------------------------------------------------------------------------
@node dos functions, dpmi functions, debugging functions, Functional Categories
@unnumberedsec dos functions
@menu
* bdos::
* bdosptr::
* delay::
* _dos_close::
* _dos_commit::
* _dos_creat::
* _dos_creatnew::
* _dos_findfirst::
* _dos_findnext::
* _dos_getdate::
* _dos_getdiskfree::
* _dos_getdrive::
* _dos_getfileattr::
* _dos_getftime::
* _dos_gettime::
* _dos_lk64::
* _dos_lock::
* _dos_open::
* _dos_read::
* _dos_setdate::
* _dos_setdrive::
* _dos_setfileattr::
* _dos_setftime::
* _dos_settime::
* _dos_unlk64::
* _dos_unlock::
* _dos_write::
* _doserrno::
* dosexterr::
* dostrerr::
* _flush_disk_cache::
* getcbrk::
* getdisk::
* int386::
* int386x::
* int86::
* int86x::
* intdos::
* intdosx::
* setcbrk::
* setdisk::
@end menu
@c -----------------------------------------------------------------------------
@node dpmi functions, environment functions, dos functions, Functional Categories
@unnumberedsec dpmi functions
@menu
* DPMI Overview::
* DPMI Specification::
* __dpmi_allocate_dos_memory::
* __dpmi_allocate_ldt_descriptors::
* __dpmi_allocate_linear_memory::
* __dpmi_allocate_memory::
* __dpmi_allocate_real_mode_callback::
* __dpmi_allocate_shared_memory::
* __dpmi_allocate_specific_ldt_descriptor::
* __dpmi_clear_debug_watchpoint::
* __dpmi_create_alias_descriptor::
* __dpmi_discard_page_contents::
* __dpmi_free_dos_memory::
* __dpmi_free_ldt_descriptor::
* __dpmi_free_memory::
* __dpmi_free_physical_address_mapping::
* __dpmi_free_real_mode_callback::
* __dpmi_free_serialization_on_shared_memory::
* __dpmi_free_shared_memory::
* __dpmi_get_and_disable_virtual_interrupt_state::
* __dpmi_get_and_enable_virtual_interrupt_state::
* __dpmi_get_and_set_virtual_interrupt_state::
* __dpmi_get_capabilities::
* __dpmi_get_coprocessor_status::
* __dpmi_get_descriptor::
* __dpmi_get_descriptor_access_rights::
* __dpmi_get_extended_exception_handler_vector_pm::
* __dpmi_get_extended_exception_handler_vector_rm::
* __dpmi_get_free_memory_information::
* __dpmi_get_memory_block_size_and_base::
* __dpmi_get_memory_information::
* __dpmi_get_multiple_descriptors::
* __dpmi_get_page_attributes::
* __dpmi_get_page_size::
* __dpmi_get_processor_exception_handler_vector::
* __dpmi_get_protected_mode_interrupt_vector::
* __dpmi_get_raw_mode_switch_addr::
* __dpmi_get_real_mode_interrupt_vector::
* __dpmi_get_segment_base_address::
* __dpmi_get_segment_limit::
* __dpmi_get_selector_increment_value::
* __dpmi_get_state_of_debug_watchpoint::
* __dpmi_get_state_save_restore_addr::
* __dpmi_get_vendor_specific_api_entry_point::
* __dpmi_get_version::
* __dpmi_get_virtual_interrupt_state::
* __dpmi_install_resident_service_provider_callback::
* __dpmi_int::
* __dpmi_lock_linear_region::
* __dpmi_map_conventional_memory_in_memory_block::
* __dpmi_map_device_in_memory_block::
* __dpmi_mark_page_as_demand_paging_candidate::
* __dpmi_mark_real_mode_region_as_pageable::
* __dpmi_physical_address_mapping::
* __dpmi_relock_real_mode_region::
* __dpmi_reset_debug_watchpoint::
* __dpmi_resize_dos_memory::
* __dpmi_resize_linear_memory::
* __dpmi_resize_memory::
* __dpmi_segment_to_descriptor::
* __dpmi_serialize_on_shared_memory::
* __dpmi_set_coprocessor_emulation::
* __dpmi_set_debug_watchpoint::
* __dpmi_set_descriptor::
* __dpmi_set_descriptor_access_rights::
* __dpmi_set_extended_exception_handler_vector_pm::
* __dpmi_set_extended_exception_handler_vector_rm::
* __dpmi_set_multiple_descriptors::
* __dpmi_set_page_attributes::
* __dpmi_set_processor_exception_handler_vector::
* __dpmi_set_protected_mode_interrupt_vector::
* __dpmi_set_real_mode_interrupt_vector::
* __dpmi_set_segment_base_address::
* __dpmi_set_segment_limit::
* __dpmi_simulate_real_mode_interrupt::
* __dpmi_simulate_real_mode_procedure_iret::
* __dpmi_simulate_real_mode_procedure_retf::
* __dpmi_simulate_real_mode_procedure_retf_stack::
* __dpmi_terminate_and_stay_resident::
* __dpmi_unlock_linear_region::
* __dpmi_yield::
* _go32_dpmi_allocate_dos_memory::
* _go32_dpmi_allocate_iret_wrapper::
* _go32_dpmi_allocate_real_mode_callback_iret::
* _go32_dpmi_allocate_real_mode_callback_retf::
* _go32_dpmi_chain_protected_mode_interrupt_vector::
* _go32_dpmi_free_dos_memory::
* _go32_dpmi_free_iret_wrapper::
* _go32_dpmi_free_real_mode_callback::
* _go32_dpmi_get_free_memory_information::
* _go32_dpmi_get_protected_mode_interrupt_vector::
* _go32_dpmi_get_real_mode_interrupt_vector::
* _go32_dpmi_remaining_physical_memory::
* _go32_dpmi_remaining_virtual_memory::
* _go32_dpmi_resize_dos_memory::
* _go32_dpmi_set_protected_mode_interrupt_vector::
* _go32_dpmi_set_real_mode_interrupt_vector::
* _go32_dpmi_simulate_fcall::
* _go32_dpmi_simulate_fcall_iret::
* _go32_dpmi_simulate_int::
* _go32_info_block::
@end menu
@c -----------------------------------------------------------------------------
@node environment functions, file system functions, dpmi functions, Functional Categories
@unnumberedsec environment functions
@menu
* getenv::
* putenv::
* setenv::
* unsetenv::
@end menu
@c -----------------------------------------------------------------------------
@node file system functions, go32 functions, environment functions, Functional Categories
@unnumberedsec file system functions
@menu
* access::
* basename::
* chdir::
* chmod::
* _chmod::
* _close::
* closedir::
* _creat::
* _creatnew::
* dirname::
* DTTOIF::
* fchdir::
* fchmod::
* File System Extensions::
* __file_tree_walk::
* findfirst::
* findnext::
* _fixpath::
* fnmatch::
* fnmerge::
* fnsplit::
* fpathconf::
* __FSEXT_add_open_handler::
* __FSEXT_alloc_fd::
* __FSEXT_call_open_handlers::
* __FSEXT_get_data::
* __FSEXT_get_function::
* __FSEXT_set_data::
* __FSEXT_set_function::
* fstatvfs::
* ftw::
* _get_fat_size::
* _get_fs_type::
* _get_volume_info::
* getcwd::
* getdfree::
* getftime::
* getwd::
* __install_dev_full::
* __install_dev_zero::
* _invent_inode::
* _is_cdrom_drive::
* _is_DOS83::
* _is_fat32::
* _is_ram_drive::
* _lfn_gen_short_fname::
* _lfn_get_ftime::
* _media_type::
* mkdir::
* mkdtemp::
* mkstemp::
* mktemp::
* _open::
* opendir::
* _preserve_fncase::
* _read::
* readdir::
* realpath::
* remove::
* _rename::
* rename::
* rewinddir::
* rmdir::
* searchpath::
* seekdir::
* setftime::
* statfs::
* statvfs::
* telldir::
* tempnam::
* umask::
* unlink::
* _use_lfn::
* utime::
* _write::
@end menu
@c -----------------------------------------------------------------------------
@node go32 functions, io functions, file system functions, Functional Categories
@unnumberedsec go32 functions
@menu
* _go32_conventional_mem_selector::
* _go32_dpmi_lock_code::
* _go32_dpmi_lock_data::
* _go32_interrupt_stack_size::
* _go32_my_cs::
* _go32_my_ds::
* _go32_my_ss::
* _go32_rmcb_stack_size::
* _go32_want_ctrl_break::
* _go32_was_ctrl_break_hit::
@end menu
@c -----------------------------------------------------------------------------
@node io functions, locale functions, go32 functions, Functional Categories
@unnumberedsec io functions
@menu
* chsize::
* __clear_fd_flags::
* __clear_fd_properties::
* close::
* creat::
* crlf2nl::
* __djgpp_share_flags::
* dup::
* dup2::
* __dup_fd_properties::
* fcntl::
* __file_exists::
* filelength::
* _get_dev_info::
* __get_fd_flags::
* __get_fd_name::
* __has_fd_properties::
* __internal_readlink::
* ioctl (DOS)::
* ioctl (General description)::
* ioctl (UNIX)::
* _is_executable::
* _is_remote_drive::
* _is_remote_handle::
* lfilelength::
* link::
* llseek::
* lock::
* lock64::
* lseek::
* lstat::
* open::
* _put_path::
* pwrite::
* read::
* readlink::
* readv::
* __set_fd_flags::
* __set_fd_properties::
* setmode::
* __solve_dir_symlinks::
* __solve_symlinks::
* stat::
* symlink::
* tell::
* truncate::
* unlock::
* unlock64::
* write::
* writev::
@end menu
@c -----------------------------------------------------------------------------
@node locale functions, math functions, io functions, Functional Categories
@unnumberedsec locale functions
@menu
* localeconv::
* mblen::
* mbstowcs::
* mbtowc::
* setlocale::
* strcoll::
* strxfrm::
* wcstombs::
* wctomb::
@end menu
@c -----------------------------------------------------------------------------
@node math functions, memory functions, locale functions, Functional Categories
@unnumberedsec math functions
@menu
* abs::
* acos::
* acosh::
* asin::
* asinh::
* atan::
* atan2::
* atanh::
* cbrt::
* ceil::
* cos::
* cosh::
* div::
* exp::
* exp10::
* exp2::
* expm1::
* fabs::
* floor::
* fmod::
* fpclassify::
* __fpclassifyd::
* __fpclassifyf::
* __fpclassifyld::
* frexp::
* hypot::
* imaxabs::
* imaxdiv::
* isfinite::
* isgreater::
* isgreaterequal::
* isinf::
* isless::
* islessequal::
* islessgreater::
* isnan::
* isnormal::
* isunordered::
* ldexp::
* ldiv::
* libm::
* lldiv::
* llrint::
* llrintf::
* llrintl::
* log::
* log10::
* log1p::
* log2::
* lrint::
* lrintf::
* lrintl::
* math_errhandling::
* matherr::
* modf::
* modfl::
* nan::
* nanf::
* nanl::
* pow::
* pow10::
* pow2::
* powi::
* signbit::
* __signbitd::
* __signbitf::
* __signbitld::
* sin::
* sincos::
* sinh::
* sqrt::
* tan::
* tanh::
@end menu
@c -----------------------------------------------------------------------------
@node memory functions, misc functions, math functions, Functional Categories
@unnumberedsec memory functions
@menu
* alloca::
* bcmp::
* bcopy::
* brk::
* bzero::
* calloc::
* cfree::
* __djgpp_map_physical_memory::
* __djgpp_memory_handle::
* __djgpp_memory_handle_list::
* __djgpp_memory_handle_size::
* __djgpp_nearptr_disable::
* __djgpp_nearptr_enable::
* __djgpp_set_page_attributes::
* dosmemget::
* dosmemgetb::
* dosmemgetl::
* dosmemgetw::
* dosmemput::
* dosmemputb::
* dosmemputl::
* dosmemputw::
* _far*::
* free::
* malldbgdmpfile::
* malldbgdumpfile::
* mallinfo::
* malloc::
* malloc_debug::
* malloc_verify::
* mallocmap::
* mallsethook::
* memalign::
* memccpy::
* memchr::
* memcmp::
* memcpy::
* memicmp::
* memmove::
* memset::
* movedata::
* movedatab::
* movedatal::
* movedataw::
* mprotect::
* realloc::
* sbrk::
* stackavail::
* swab::
* _sysmalloc::
* valloc::
* xfree::
* xmalloc::
* xrealloc::
@end menu
@c -----------------------------------------------------------------------------
@node misc functions, mono functions, memory functions, Functional Categories
@unnumberedsec misc functions
@menu
* assert::
* bsearch::
* dlclose::
* dlerror::
* dlerrstatmod::
* dlerrstatsym::
* dlopen::
* dlregsym::
* dlsym::
* _dlsymresolver::
* dlunregsym::
* _dxe_load::
* DXE_macros::
* _get_dos_version::
* gethostname::
* getlongpass::
* getopt::
* getpagesize::
* getpass::
* _hash2v::
* insque::
* labs::
* lfind::
* llabs::
* longjmp::
* lsearch::
* qsort::
* remque::
* setjmp::
* siglongjmp::
* sigsetjmp::
* varargs::
@end menu
@c -----------------------------------------------------------------------------
@node mono functions, posix functions, misc functions, Functional Categories
@unnumberedsec mono functions
@menu
* _mono_clear::
* _mono_printf::
* _mono_putc::
@end menu
@c -----------------------------------------------------------------------------
@node posix functions, process functions, mono functions, Functional Categories
@unnumberedsec posix functions
@menu
* confstr::
* ctermid::
* getdtablesize::
* pathconf::
* sysconf::
@end menu
@c -----------------------------------------------------------------------------
@node process functions, profiling functions, posix functions, Functional Categories
@unnumberedsec process functions
@menu
* abort::
* alarm::
* atexit::
* _check_v2_prog::
* __djgpp_spawn::
* __dosexec_find_on_path::
* exec*::
* __exit::
* _exit::
* _Exit::
* exit::
* getitimer::
* kill::
* nice::
* pause::
* setitimer::
* sleep::
* spawn*::
* system::
* usleep::
* wait::
* waitpid::
@end menu
@c -----------------------------------------------------------------------------
@node profiling functions, random number functions, process functions, Functional Categories
@unnumberedsec profiling functions
@menu
* moncontrol::
* monstartup::
@end menu
@c -----------------------------------------------------------------------------
@node random number functions, search functions, profiling functions, Functional Categories
@unnumberedsec random number functions
@menu
* initstate::
* rand::
* rand48::
* random::
* setstate::
* srand::
* srandom::
@end menu
@c -----------------------------------------------------------------------------
@node search functions, shell functions, random number functions, Functional Categories
@unnumberedsec search functions
@menu
* hcreate::
* hdestroy::
* hsearch::
@end menu
@c -----------------------------------------------------------------------------
@node shell functions, signal functions, search functions, Functional Categories
@unnumberedsec shell functions
@menu
* glob::
* globfree::
@end menu
@c -----------------------------------------------------------------------------
@node signal functions, sound functions, shell functions, Functional Categories
@unnumberedsec signal functions
@menu
* __djgpp_exception_toggle::
* __djgpp_set_ctrl_c::
* __djgpp_set_sigint_key::
* __djgpp_set_sigquit_key::
* __djgpp_traceback_exit::
* psignal::
* raise::
* sigaction::
* sigaddset::
* sigdelset::
* sigemptyset::
* sigfillset::
* sigismember::
* signal::
* sigpending::
* sigprocmask::
* Stack overflow handler::
@end menu
@c -----------------------------------------------------------------------------
@node sound functions, startup functions, signal functions, Functional Categories
@unnumberedsec sound functions
@menu
* nosound::
* sound::
@end menu
@c -----------------------------------------------------------------------------
@node startup functions, stdio functions, sound functions, Functional Categories
@unnumberedsec startup functions
@menu
* __crt0_glob_function::
* __crt0_load_environment_file::
* __crt0_setup_arguments::
* _crt0_startup_flags::
* _stklen::
@end menu
@c -----------------------------------------------------------------------------
@node stdio functions, string functions, startup functions, Functional Categories
@unnumberedsec stdio functions
@menu
* asnprintf::
* asprintf::
* clearerr::
* _djstat_describe_lossage::
* _djstat_fail_bits::
* _djstat_flags::
* _doprnt::
* _doscan::
* dprintf::
* errno::
* fclose::
* fdopen::
* feof::
* ferror::
* fflush::
* fgetc::
* fgetpos::
* fgets::
* fileno::
* _fmode::
* fopen::
* fprintf::
* fpurge::
* fputc::
* fputs::
* fread::
* freopen::
* fscanf::
* fseek::
* fseeko::
* fsetpos::
* fstat::
* fsync::
* ftell::
* ftello::
* ftruncate::
* _fwalk::
* fwrite::
* getc::
* getchar::
* gets::
* getw::
* perror::
* PRI::
* printf::
* putc::
* putchar::
* puts::
* putw::
* rewind::
* scanf::
* SCN::
* setbuf::
* setbuffer::
* setlinebuf::
* setvbuf::
* snprintf::
* sprintf::
* sscanf::
* strerror::
* strerror_r::
* sys_errlist::
* sys_nerr::
* tmpfile::
* tmpnam::
* _truename::
* _truename_sfn::
* ungetc::
* vasnprintf::
* vasprintf::
* vdprintf::
* vfprintf::
* vfscanf::
* vprintf::
* vscanf::
* vsnprintf::
* vsprintf::
* vsscanf::
@end menu
@c -----------------------------------------------------------------------------
@node string functions, sys functions, stdio functions, Functional Categories
@unnumberedsec string functions
@menu
* a64l::
* atof::
* atoi::
* atol::
* _atold::
* atoll::
* ecvt::
* ecvtbuf::
* fcvt::
* fcvtbuf::
* ffs::
* gcvt::
* index::
* itoa::
* l64a::
* regcomp::
* regerror::
* regexec::
* regfree::
* rindex::
* stpcpy::
* stpncpy::
* strcasecmp::
* strcat::
* strchr::
* strcmp::
* strcpy::
* strcspn::
* strdup::
* stricmp::
* strlcat::
* strlcpy::
* strlen::
* strlwr::
* strncasecmp::
* strncat::
* strncmp::
* strncpy::
* strndup::
* strnicmp::
* strnlen::
* strpbrk::
* strrchr::
* strsep::
* strspn::
* strstr::
* strtod::
* strtof::
* strtoimax::
* strtok::
* strtok_r::
* strtol::
* strtold::
* _strtold::
* strtoll::
* strtoul::
* strtoull::
* strtoumax::
* strupr::
@end menu
@c -----------------------------------------------------------------------------
@node sys functions, termios functions, string functions, Functional Categories
@unnumberedsec sys functions
@menu
* flock::
@end menu
@c -----------------------------------------------------------------------------
@node termios functions, time functions, sys functions, Functional Categories
@unnumberedsec termios functions
@menu
* cfgetispeed::
* cfgetospeed::
* cfmakeraw::
* cfsetispeed::
* cfsetospeed::
* cfsetspeed::
* __libc_termios_exist_queue::
* __libc_termios_init::
* tcdrain::
* tcflow::
* tcflush::
* tcgetattr::
* tcgetpgrp::
* tcsendbreak::
* tcsetattr::
* tcsetpgrp::
* Termios functions::
@end menu
@c -----------------------------------------------------------------------------
@node time functions, unistd functions, termios functions, Functional Categories
@unnumberedsec time functions
@menu
* asctime::
* asctime_r::
* clock::
* ctime::
* ctime_r::
* difftime::
* ftime::
* getdate::
* gettime::
* gettimeofday::
* gmtime::
* gmtime_r::
* localtime::
* localtime_r::
* mktime::
* rawclock::
* _rdtsc::
* setdate::
* settime::
* settimeofday::
* strftime::
* time::
* times::
* tzset::
* tzsetwall::
* uclock::
* utimes::
@end menu
@c -----------------------------------------------------------------------------
@node unistd functions, unix functions, time functions, Functional Categories
@unnumberedsec unistd functions
@menu
* llockf::
* lockf::
@end menu
@c -----------------------------------------------------------------------------
@node unix functions, , unistd functions, Functional Categories
@unnumberedsec unix functions
@menu
* addmntent::
* chown::
* endgrent::
* endmntent::
* endpwent::
* fchown::
* fgetgrent::
* fork::
* getegid::
* geteuid::
* getgid::
* getgrent::
* getgrgid::
* getgrnam::
* getgroups::
* getlogin::
* getmntent::
* getpgrp::
* getpid::
* getppid::
* getpwent::
* getpwnam::
* getpwuid::
* getrlimit::
* getrusage::
* getuid::
* hasmntopt::
* isatty::
* lchown::
* mkfifo::
* mknod::
* pclose::
* pipe::
* popen::
* select::
* setgid::
* setgrent::
* setmntent::
* setpgid::
* setpwent::
* setrlimit::
* setsid::
* setuid::
* sync::
* ttyname::
* uname::
* vfork::
@end menu
@c -----------------------------------------------------------------------------
@node Alphabetical List, Unimplemented, Functional Categories, Top
@unnumbered Alphabetical List

@menu
* _8087::
* a64l::
* abort::
* abs::
* access::
* acos::
* acosh::
* addmntent::
* alarm::
* alloca::
* asctime::
* asctime_r::
* asin::
* asinh::
* asnprintf::
* asprintf::
* assert::
* atan::
* atan2::
* atanh::
* atexit::
* atof::
* atoi::
* atol::
* _atold::
* atoll::
* basename::
* bcmp::
* bcopy::
* bdos::
* bdosptr::
* _bios_disk::
* _bios_equiplist::
* _bios_keybrd::
* _bios_memsize::
* _bios_printer::
* _bios_serialcom::
* _bios_timeofday::
* bioscom::
* biosdisk::
* biosequip::
* bioskey::
* biosmemory::
* biosprint::
* biostime::
* blinkvideo::
* brk::
* bsearch::
* bzero::
* calloc::
* cbrt::
* ceil::
* cfgetispeed::
* cfgetospeed::
* cfmakeraw::
* cfree::
* cfsetispeed::
* cfsetospeed::
* cfsetspeed::
* cgets::
* chdir::
* _check_v2_prog::
* chmod::
* _chmod::
* chown::
* chsize::
* cleanup_client::
* _clear87::
* __clear_fd_flags::
* __clear_fd_properties::
* clearerr::
* clock::
* close::
* _close::
* closedir::
* clreol::
* clrscr::
* confstr::
* _conio_gettext::
* _conio_kbhit::
* _control87::
* cos::
* cosh::
* cprintf::
* cputs::
* creat::
* _creat::
* _creatnew::
* crlf2nl::
* __crt0_glob_function::
* __crt0_load_environment_file::
* __crt0_setup_arguments::
* _crt0_startup_flags::
* cscanf::
* ctermid::
* ctime::
* ctime_r::
* delay::
* delline::
* _detect_80387::
* difftime::
* dirname::
* disable::
* div::
* __djgpp_exception_toggle::
* __djgpp_map_physical_memory::
* __djgpp_memory_handle::
* __djgpp_memory_handle_list::
* __djgpp_memory_handle_size::
* __djgpp_nearptr_disable::
* __djgpp_nearptr_enable::
* __djgpp_set_ctrl_c::
* __djgpp_set_page_attributes::
* __djgpp_set_sigint_key::
* __djgpp_set_sigquit_key::
* __djgpp_share_flags::
* __djgpp_spawn::
* __djgpp_traceback_exit::
* _djstat_describe_lossage::
* _djstat_fail_bits::
* _djstat_flags::
* dlclose::
* dlerror::
* dlerrstatmod::
* dlerrstatsym::
* dlopen::
* dlregsym::
* dlsym::
* _dlsymresolver::
* dlunregsym::
* _doprnt::
* _dos_close::
* _dos_commit::
* _dos_creat::
* _dos_creatnew::
* _dos_findfirst::
* _dos_findnext::
* _dos_getdate::
* _dos_getdiskfree::
* _dos_getdrive::
* _dos_getfileattr::
* _dos_getftime::
* _dos_gettime::
* _dos_lk64::
* _dos_lock::
* _dos_open::
* _dos_read::
* _dos_setdate::
* _dos_setdrive::
* _dos_setfileattr::
* _dos_setftime::
* _dos_settime::
* _dos_unlk64::
* _dos_unlock::
* _dos_write::
* _doscan::
* _doserrno::
* __dosexec_find_on_path::
* dosexterr::
* dosmemget::
* dosmemgetb::
* dosmemgetl::
* dosmemgetw::
* dosmemput::
* dosmemputb::
* dosmemputl::
* dosmemputw::
* dostrerr::
* DPMI Overview::
* DPMI Specification::
* __dpmi_allocate_dos_memory::
* __dpmi_allocate_ldt_descriptors::
* __dpmi_allocate_linear_memory::
* __dpmi_allocate_memory::
* __dpmi_allocate_real_mode_callback::
* __dpmi_allocate_shared_memory::
* __dpmi_allocate_specific_ldt_descriptor::
* __dpmi_clear_debug_watchpoint::
* __dpmi_create_alias_descriptor::
* __dpmi_discard_page_contents::
* __dpmi_free_dos_memory::
* __dpmi_free_ldt_descriptor::
* __dpmi_free_memory::
* __dpmi_free_physical_address_mapping::
* __dpmi_free_real_mode_callback::
* __dpmi_free_serialization_on_shared_memory::
* __dpmi_free_shared_memory::
* __dpmi_get_and_disable_virtual_interrupt_state::
* __dpmi_get_and_enable_virtual_interrupt_state::
* __dpmi_get_and_set_virtual_interrupt_state::
* __dpmi_get_capabilities::
* __dpmi_get_coprocessor_status::
* __dpmi_get_descriptor::
* __dpmi_get_descriptor_access_rights::
* __dpmi_get_extended_exception_handler_vector_pm::
* __dpmi_get_extended_exception_handler_vector_rm::
* __dpmi_get_free_memory_information::
* __dpmi_get_memory_block_size_and_base::
* __dpmi_get_memory_information::
* __dpmi_get_multiple_descriptors::
* __dpmi_get_page_attributes::
* __dpmi_get_page_size::
* __dpmi_get_processor_exception_handler_vector::
* __dpmi_get_protected_mode_interrupt_vector::
* __dpmi_get_raw_mode_switch_addr::
* __dpmi_get_real_mode_interrupt_vector::
* __dpmi_get_segment_base_address::
* __dpmi_get_segment_limit::
* __dpmi_get_selector_increment_value::
* __dpmi_get_state_of_debug_watchpoint::
* __dpmi_get_state_save_restore_addr::
* __dpmi_get_vendor_specific_api_entry_point::
* __dpmi_get_version::
* __dpmi_get_virtual_interrupt_state::
* __dpmi_install_resident_service_provider_callback::
* __dpmi_int::
* __dpmi_lock_linear_region::
* __dpmi_map_conventional_memory_in_memory_block::
* __dpmi_map_device_in_memory_block::
* __dpmi_mark_page_as_demand_paging_candidate::
* __dpmi_mark_real_mode_region_as_pageable::
* __dpmi_physical_address_mapping::
* __dpmi_relock_real_mode_region::
* __dpmi_reset_debug_watchpoint::
* __dpmi_resize_dos_memory::
* __dpmi_resize_linear_memory::
* __dpmi_resize_memory::
* __dpmi_segment_to_descriptor::
* __dpmi_serialize_on_shared_memory::
* __dpmi_set_coprocessor_emulation::
* __dpmi_set_debug_watchpoint::
* __dpmi_set_descriptor::
* __dpmi_set_descriptor_access_rights::
* __dpmi_set_extended_exception_handler_vector_pm::
* __dpmi_set_extended_exception_handler_vector_rm::
* __dpmi_set_multiple_descriptors::
* __dpmi_set_page_attributes::
* __dpmi_set_processor_exception_handler_vector::
* __dpmi_set_protected_mode_interrupt_vector::
* __dpmi_set_real_mode_interrupt_vector::
* __dpmi_set_segment_base_address::
* __dpmi_set_segment_limit::
* __dpmi_simulate_real_mode_interrupt::
* __dpmi_simulate_real_mode_procedure_iret::
* __dpmi_simulate_real_mode_procedure_retf::
* __dpmi_simulate_real_mode_procedure_retf_stack::
* __dpmi_terminate_and_stay_resident::
* __dpmi_unlock_linear_region::
* __dpmi_yield::
* dprintf::
* DTTOIF::
* dup::
* dup2::
* __dup_fd_properties::
* _dxe_load::
* DXE_macros::
* ecvt::
* ecvtbuf::
* edi_init::
* enable::
* endgrent::
* endmntent::
* endpwent::
* errno::
* exec*::
* __exit::
* _exit::
* _Exit::
* exit::
* exp::
* exp10::
* exp2::
* expm1::
* fabs::
* _far*::
* fchdir::
* fchmod::
* fchown::
* fclose::
* fcntl::
* fcvt::
* fcvtbuf::
* fdopen::
* feof::
* ferror::
* fflush::
* ffs::
* fgetc::
* fgetgrent::
* fgetpos::
* fgets::
* File System Extensions::
* __file_exists::
* __file_tree_walk::
* filelength::
* fileno::
* findfirst::
* findnext::
* _fixpath::
* flock::
* floor::
* _flush_disk_cache::
* fmod::
* _fmode::
* fnmatch::
* fnmerge::
* fnsplit::
* fopen::
* fork::
* fpathconf::
* fpclassify::
* __fpclassifyd::
* __fpclassifyf::
* __fpclassifyld::
* _fpreset::
* fprintf::
* fpurge::
* fputc::
* fputs::
* fread::
* free::
* freopen::
* frexp::
* fscanf::
* fseek::
* fseeko::
* fsetpos::
* __FSEXT_add_open_handler::
* __FSEXT_alloc_fd::
* __FSEXT_call_open_handlers::
* __FSEXT_get_data::
* __FSEXT_get_function::
* __FSEXT_set_data::
* __FSEXT_set_function::
* fstat::
* fstatvfs::
* fsync::
* ftell::
* ftello::
* ftime::
* ftruncate::
* ftw::
* _fwalk::
* fwrite::
* gcvt::
* _get_dev_info::
* _get_dos_version::
* __get_extended_key_string::
* _get_fat_size::
* __get_fd_flags::
* __get_fd_name::
* _get_fs_type::
* _get_volume_info::
* getc::
* getcbrk::
* getch::
* getchar::
* getche::
* getcwd::
* getdate::
* getdfree::
* getdisk::
* getdtablesize::
* getegid::
* getenv::
* geteuid::
* getftime::
* getgid::
* getgrent::
* getgrgid::
* getgrnam::
* getgroups::
* gethostname::
* getitimer::
* getkey::
* getlogin::
* getlongpass::
* getmntent::
* getopt::
* getpagesize::
* getpass::
* getpgrp::
* getpid::
* getppid::
* getpwent::
* getpwnam::
* getpwuid::
* getrlimit::
* getrusage::
* gets::
* gettext::
* gettextinfo::
* gettime::
* gettimeofday::
* getuid::
* getw::
* getwd::
* getxkey::
* glob::
* globfree::
* gmtime::
* gmtime_r::
* _go32_conventional_mem_selector::
* _go32_dpmi_allocate_dos_memory::
* _go32_dpmi_allocate_iret_wrapper::
* _go32_dpmi_allocate_real_mode_callback_iret::
* _go32_dpmi_allocate_real_mode_callback_retf::
* _go32_dpmi_chain_protected_mode_interrupt_vector::
* _go32_dpmi_free_dos_memory::
* _go32_dpmi_free_iret_wrapper::
* _go32_dpmi_free_real_mode_callback::
* _go32_dpmi_get_free_memory_information::
* _go32_dpmi_get_protected_mode_interrupt_vector::
* _go32_dpmi_get_real_mode_interrupt_vector::
* _go32_dpmi_lock_code::
* _go32_dpmi_lock_data::
* _go32_dpmi_remaining_physical_memory::
* _go32_dpmi_remaining_virtual_memory::
* _go32_dpmi_resize_dos_memory::
* _go32_dpmi_set_protected_mode_interrupt_vector::
* _go32_dpmi_set_real_mode_interrupt_vector::
* _go32_dpmi_simulate_fcall::
* _go32_dpmi_simulate_fcall_iret::
* _go32_dpmi_simulate_int::
* _go32_info_block::
* _go32_interrupt_stack_size::
* _go32_my_cs::
* _go32_my_ds::
* _go32_my_ss::
* _go32_rmcb_stack_size::
* _go32_want_ctrl_break::
* _go32_was_ctrl_break_hit::
* gotoxy::
* gppconio_init::
* __has_fd_properties::
* _hash2v::
* hasmntopt::
* hcreate::
* hdestroy::
* highvideo::
* hsearch::
* htonl::
* htons::
* hypot::
* imaxabs::
* imaxdiv::
* inb::
* index::
* initstate::
* inp::
* inportb::
* inportl::
* inportsb::
* inportsl::
* inportsw::
* inportw::
* inpw::
* insline::
* insque::
* __install_dev_full::
* __install_dev_zero::
* int386::
* int386x::
* int86::
* int86x::
* intdos::
* intdosx::
* intensevideo::
* __internal_readlink::
* _invent_inode::
* ioctl (DOS)::
* ioctl (General description)::
* ioctl (UNIX)::
* _is_cdrom_drive::
* _is_DOS83::
* _is_executable::
* _is_fat32::
* _is_ram_drive::
* _is_remote_drive::
* _is_remote_handle::
* isalnum::
* isalpha::
* isascii::
* isatty::
* isblank::
* iscntrl::
* isdigit::
* isfinite::
* isgraph::
* isgreater::
* isgreaterequal::
* isinf::
* isless::
* islessequal::
* islessgreater::
* islower::
* isnan::
* isnormal::
* isprint::
* ispunct::
* isspace::
* isunordered::
* isupper::
* isxdigit::
* itoa::
* kbhit::
* kill::
* l64a::
* labs::
* lchown::
* ldexp::
* ldiv::
* lfilelength::
* lfind::
* _lfn_gen_short_fname::
* _lfn_get_ftime::
* __libc_termios_exist_queue::
* __libc_termios_init::
* libm::
* link::
* llabs::
* lldiv::
* llockf::
* llrint::
* llrintf::
* llrintl::
* llseek::
* load_npx::
* localeconv::
* localtime::
* localtime_r::
* lock::
* lock64::
* lockf::
* log::
* log10::
* log1p::
* log2::
* longjmp::
* lowvideo::
* lrint::
* lrintf::
* lrintl::
* lsearch::
* lseek::
* lstat::
* malldbgdmpfile::
* malldbgdumpfile::
* mallinfo::
* malloc::
* malloc_debug::
* malloc_verify::
* mallocmap::
* mallsethook::
* math_errhandling::
* matherr::
* mblen::
* mbstowcs::
* mbtowc::
* _media_type::
* memalign::
* memccpy::
* memchr::
* memcmp::
* memcpy::
* memicmp::
* memmove::
* memset::
* mkdir::
* mkdtemp::
* mkfifo::
* mknod::
* mkstemp::
* mktemp::
* mktime::
* modf::
* modfl::
* moncontrol::
* _mono_clear::
* _mono_printf::
* _mono_putc::
* monstartup::
* movedata::
* movedatab::
* movedatal::
* movedataw::
* movetext::
* mprotect::
* _my_cs::
* _my_ds::
* _my_ss::
* nan::
* nanf::
* nanl::
* nice::
* normvideo::
* nosound::
* ntohl::
* ntohs::
* open::
* _open::
* opendir::
* outb::
* outp::
* outportb::
* outportl::
* outportsb::
* outportsl::
* outportsw::
* outportw::
* outpw::
* pathconf::
* pause::
* pclose::
* perror::
* pipe::
* popen::
* pow::
* pow10::
* pow2::
* powi::
* _preserve_fncase::
* PRI::
* printf::
* psignal::
* _put_path::
* putc::
* putch::
* putchar::
* putenv::
* puts::
* puttext::
* putw::
* pwrite::
* qsort::
* raise::
* rand::
* rand48::
* random::
* rawclock::
* _rdtsc::
* read::
* _read::
* read_child::
* read_sel_addr::
* readdir::
* readlink::
* readv::
* realloc::
* realpath::
* redir_cmdline_delete::
* redir_cmdline_parse::
* redir_debug_init::
* redir_to_child::
* redir_to_debugger::
* regcomp::
* regerror::
* regexec::
* regfree::
* remove::
* remque::
* _rename::
* rename::
* rewind::
* rewinddir::
* rindex::
* rmdir::
* run_child::
* save_npx::
* sbrk::
* scanf::
* SCN::
* Screen Variables::
* ScreenClear::
* ScreenCols::
* ScreenGetChar::
* ScreenGetCursor::
* ScreenMode::
* ScreenPutChar::
* ScreenPutString::
* ScreenRetrieve::
* ScreenRows::
* ScreenSetCursor::
* ScreenUpdate::
* ScreenUpdateLine::
* ScreenVisualBell::
* searchpath::
* seekdir::
* select::
* __set_fd_flags::
* __set_fd_properties::
* _set_screen_lines::
* setbuf::
* setbuffer::
* setcbrk::
* _setcursortype::
* setdate::
* setdisk::
* setenv::
* setftime::
* setgid::
* setgrent::
* setitimer::
* setjmp::
* setlinebuf::
* setlocale::
* setmntent::
* setmode::
* setpgid::
* setpwent::
* setrlimit::
* setsid::
* setstate::
* settime::
* settimeofday::
* setuid::
* setvbuf::
* sigaction::
* sigaddset::
* sigdelset::
* sigemptyset::
* sigfillset::
* sigismember::
* siglongjmp::
* signal::
* signbit::
* __signbitd::
* __signbitf::
* __signbitld::
* sigpending::
* sigprocmask::
* sigsetjmp::
* sin::
* sincos::
* sinh::
* sleep::
* snprintf::
* __solve_dir_symlinks::
* __solve_symlinks::
* sound::
* spawn*::
* sprintf::
* sqrt::
* srand::
* srandom::
* sscanf::
* Stack overflow handler::
* stackavail::
* stat::
* statfs::
* _status87::
* statvfs::
* _stklen::
* stpcpy::
* stpncpy::
* strcasecmp::
* strcat::
* strchr::
* strcmp::
* strcoll::
* strcpy::
* strcspn::
* strdup::
* strerror::
* strerror_r::
* strftime::
* stricmp::
* strlcat::
* strlcpy::
* strlen::
* strlwr::
* strncasecmp::
* strncat::
* strncmp::
* strncpy::
* strndup::
* strnicmp::
* strnlen::
* strpbrk::
* strrchr::
* strsep::
* strspn::
* strstr::
* strtod::
* strtof::
* strtoimax::
* strtok::
* strtok_r::
* strtol::
* strtold::
* _strtold::
* strtoll::
* strtoul::
* strtoull::
* strtoumax::
* strupr::
* strxfrm::
* swab::
* symlink::
* syms_init::
* syms_line2val::
* syms_listwild::
* syms_module::
* syms_name2val::
* syms_val2line::
* syms_val2name::
* sync::
* sys_errlist::
* sys_nerr::
* sysconf::
* _sysmalloc::
* system::
* tan::
* tanh::
* tcdrain::
* tcflow::
* tcflush::
* tcgetattr::
* tcgetpgrp::
* tcsendbreak::
* tcsetattr::
* tcsetpgrp::
* tell::
* telldir::
* tempnam::
* Termios functions::
* textattr::
* textbackground::
* textcolor::
* textmode::
* time::
* times::
* tmpfile::
* tmpnam::
* toascii::
* _tolower::
* tolower::
* _toupper::
* toupper::
* _truename::
* _truename_sfn::
* truncate::
* ttyname::
* tzset::
* tzsetwall::
* uclock::
* umask::
* uname::
* ungetc::
* ungetch::
* unlink::
* unlock::
* unlock64::
* unsetenv::
* _use_lfn::
* usleep::
* utime::
* utimes::
* v2loadimage::
* valloc::
* varargs::
* vasnprintf::
* vasprintf::
* vdprintf::
* vfork::
* vfprintf::
* vfscanf::
* vprintf::
* vscanf::
* vsnprintf::
* vsprintf::
* vsscanf::
* wait::
* waitpid::
* wcstombs::
* wctomb::
* wherex::
* wherey::
* wild::
* window::
* write::
* _write::
* write_child::
* write_sel_addr::
* writev::
* xfree::
* xmalloc::
* xrealloc::
@end menu
@c -----------------------------------------------------------------------------
@node _8087, a64l, , Alphabetical List
@unnumberedsec _8087
@c From file ./emu387/fpu.txh
@vindex _8087
@vindex 387@r{ environment variable, and numeric coprocessor detection}
@vindex 387@r{ environment variable, and math coprocessor detection}
@subheading Syntax

@example
#include <dos.h>

extern int _8087;
@end example

@subheading Description

This variable is provided for compatibility with other DOS compilers.
It contains @code{3} if a numeric coprocessor is installed, otherwise
@code{0}.  If the environment variable @code{387} is set to either
@samp{y} or @samp{n}, the value of @code{_8087} reflects the override
(i.e., @code{_8087} is unconditionally assigned the value 3 if
@code{387} is set to @samp{y}, 0 if it is set to @samp{n}).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node a64l, abort, _8087, Alphabetical List
@unnumberedsec a64l
@c From file ./posix/stdlib/a64l.txh
@findex a64l
@subheading Syntax

@example
#include <stdlib.h>

long a64l(const char *string);
@end example

@subheading Description

This function takes a pointer to a radix-64 representation, with the
first digit the least significant, and returns the corresponding
@code{long} value.

If @var{string} contains more than six characters, only the first six are
used.  If the first six characters of @var{string} contain a null terminator,
only those characters before the null terminator are used.
@code{a64l} will scan the string from left to right, with the least
significant digit on the left, decoding each character as a 6-bit radix-64
number.

The radix-64 representation used by this function is described in the
documentation for the @code{l64a} function (@pxref{l64a}).

@subheading Return Value

Returns the @code{long} value resulting from the conversion of the contents
of @var{string}, or @code{0L} if @var{string} is @code{NULL}, points to an
empty string, or points to an invalid string (i.e. one not generated by a
previous call to @code{l64a}).  If the result would overflow a @code{long},
the conversion of @samp{/2BIG/} (@code{1144341633L}) is returned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
This function is new to the Posix 1003.1-200x draft
@end enumerate
@c -----------------------------------------------------------------------------
@node abort, abs, a64l, Alphabetical List
@unnumberedsec abort
@c From file ./ansi/stdlib/abort.txh
@findex abort
@subheading Syntax

@example
#include <stdlib.h>

void abort(void);
@end example

@subheading Description

When you call @code{abort}, the message "Abort!" is printed on stdout
and the program is aborted by calling @code{raise (SIGABRT)}
(@pxref{signal, SIGABRT}).  By default, this causes the CPU registers
and the call frame stack dump to be printed, and the program then exits
with an exit code of -1 (255).  If the @code{SIGABRT} signal is caught
by a handler that returns, the program exits with an exit code of 1.

@subheading Return Value

This function does not return.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
if ((q = malloc(100)) == NULL)
  abort();
@end example

@c -----------------------------------------------------------------------------
@node abs, access, abort, Alphabetical List
@unnumberedsec abs
@c From file ./ansi/stdlib/abs.txh
@findex abs
@subheading Syntax

@example
#include <stdlib.h>

int abs(int value);
@end example

@subheading Return Value

The absolute value of @code{value} is returned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
int sq = 7;
sq = sq * abs(sq) + 1;
@end example

@c -----------------------------------------------------------------------------
@node access, acos, abs, Alphabetical List
@unnumberedsec access
@c From file ./posix/unistd/access.txh
@findex access
@subheading Syntax

@example
#include <unistd.h>

int access(const char *filename, int flags);
@end example

@subheading Description

This function determines what kind of access modes a given file allows. 
The parameter @var{flags} is the logical @code{or} of one or more of the
following flags:

@table @code

@item R_OK

Request if the file is readable.  Since all files are readable under
MS-DOS, this access mode always exists. 

@item W_OK

Request if the file is writable.

@item X_OK

Request if the file is executable.

@item F_OK

Request if the file exists.

@item D_OK

Request if the file is really a directory.

@end table

@subheading Return Value

Zero if the requested access mode is allowed, nonzero if not. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
if (access("file.ext", W_OK))
  return ERROR_CANNOT_WRITE;
open("file.ext", O_RDWR);
@end example

@c -----------------------------------------------------------------------------
@node acos, acosh, access, Alphabetical List
@unnumberedsec acos
@c From file ./ansi/math/acos.txh
@findex acos
@subheading Syntax

@example
#include <math.h>

double acos(double x);
@end example

@subheading Description

This function returns the angle in the range @code{[0..Pi]} radians
whose cosine is @var{x}.  If the absolute value of @var{x} is greater
than 1, a domain error occurs, and @code{errno} is set to @code{EDOM}.

@subheading Return Value

The arc cosine, in radians, of @var{x}.  If the absolute value of
@var{x} is greater than 1, the function returns a @code{NaN}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node acosh, addmntent, acos, Alphabetical List
@unnumberedsec acosh
@c From file ./ansi/math/acosh.txh
@findex acosh
@subheading Syntax

@example
#include <math.h>

double acosh(double x);
@end example

@subheading Description

This function returns the inverse hyperbolic cosine of @var{x}.

@subheading Return Value

The inverse hyperbolic cosine of @var{x}.  If the value of @var{x} is
less than 1, the return value is @code{NaN} and @code{errno} is set to
@code{EDOM}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node addmntent, alarm, acosh, Alphabetical List
@unnumberedsec addmntent
@c From file ./compat/mntent/mntent.txh
@findex addmntent
@subheading Syntax

@example
#include <mntent.h>

int addmntent(FILE *filep, const struct mntent *mnt);
@end example

@subheading Description

This function is a no-op for MS-DOS, but is provided to assist in Unix
ports.  @xref{getmntent}.

@subheading Return Value

This function always returns nonzero to signify an error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node alarm, alloca, addmntent, Alphabetical List
@unnumberedsec alarm
@c From file ./posix/unistd/alarm.txh
@findex alarm
@subheading Syntax

@example
#include <unistd.h>

unsigned alarm(unsigned seconds);
@end example

@subheading Description

This function causes the signal @code{SIGALRM} to be raised in
@var{seconds} seconds.  A value of zero for @var{seconds} cancels any
pending alarm.  If an alarm has previously been set, the new alarm delay
will supercede the prior call.

Note that signals in DJGPP are deferred when the program is inside a
real-mode (e.g., DOS) call or isn't touching its data; see @ref{signal},
for more details.

A misfeature of Windows 9X prevents the timer tick interrupt from being
delivered to programs that are in the background (i.e. don't have the
focus), even though the program itself might continue to run, if you
uncheck the @cite{Background: Always suspend} property in the Property
Sheets.  Therefore, @code{alarm} will not work in background programs on
Windows 9X.

@subheading Return Value

The number of seconds remaining on the timer (i.e. always @var{seconds}).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
signal(SIGALRM,my_alarm_routine);
alarm(5);
@end example

@c -----------------------------------------------------------------------------
@node alloca, asctime, alarm, Alphabetical List
@unnumberedsec alloca
@c From file ./compat/stdlib/alloca.txh
@findex alloca
@subheading Syntax

@example
#include <stdlib.h>

void *alloca(size_t _size)
@end example

@subheading Description

Allocate memory that will be automatically released when the current
procedure exits.  Note that, when compiling with gcc, alloca is a
built-in function and not a library call.

@subheading Return Value

A pointer to the memory, else NULL.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
q = alloca(strlen(x)+1);
strcpy(q, x);
@end example

@c -----------------------------------------------------------------------------
@node asctime, asctime_r, alloca, Alphabetical List
@unnumberedsec asctime
@c From file ./ansi/time/ctime.txh
@findex asctime
@subheading Syntax

@example
#include <time.h>

char *asctime(const struct tm *tptr);
@end example

@subheading Description

This function returns a string representing the time from
@var{tptr}.  The string returned is always 26 characters and has this
format:

@example
Sun Jan 01 12:34:56 1993\n\0
@end example

The string pointed to is in a static buffer and will be overwritten with
each call to @code{asctime}.  The string should be copied if it needs to be
preserved. 
@xref{asctime_r}, for an alternate interface that allows the caller
to provide a buffer to store the string.

@xref{gmtime}, for a description of type @code{struct tm}.

@subheading Return Value

A pointer to a static buffer containing the string representing the time.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
time_t now;
time(&now);
printf("The current time is %s", asctime(localtime(&now)));
@end example

@c -----------------------------------------------------------------------------
@node asctime_r, asin, asctime, Alphabetical List
@unnumberedsec asctime_r
@c From file ./ansi/time/ctime.txh
@findex asctime_r
@subheading Syntax

@example
#include <time.h>

char *asctime_r(const struct tm * restrict tptr, char * restrict buf);
@end example

@subheading Description

This function returns a string representing the time from @var{tptr}.
The string returned is always 26 characters and has this
format:

@example
Sun Jan 01 12:34:56 1993\n\0
@end example

@xref{asctime}, for an alternate ISO Standard interface.

@xref{gmtime}, for a description of type @code{struct tm}.

@subheading Return Value

A pointer to @var{buf} containing the character representation of the time.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
time_t now;
struct tm tm;
char buf[26];

time(&now);
printf("The current time is %s", asctime_r(localtime_r(&now,&tm),buf));
@end example

@c -----------------------------------------------------------------------------
@node asin, asinh, asctime_r, Alphabetical List
@unnumberedsec asin
@c From file ./ansi/math/asin.txh
@findex asin
@subheading Syntax

@example
#include <math.h>

double asin(double x);
@end example

@subheading Description

This function returns the angle in the range @code{[-Pi/2..Pi/2]} whose
sine is @var{x}.

@subheading Return Value

The inverse sine, in radians, of @var{x}.  If the absolute value of
@var{x} is greater than 1, the return value is @code{NaN} and
@code{errno} is set to @code{EDOM}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node asinh, asnprintf, asin, Alphabetical List
@unnumberedsec asinh
@c From file ./ansi/math/asinh.txh
@findex asinh
@subheading Syntax

@example
#include <math.h>

double asinh(double x);
@end example

@subheading Description

This function returns the inverse hyperbolic sine of the argument
@var{x}. 

@subheading Return Value

The inverse hyperbolic sine of @var{x}.  If the argument @var{x} is a
@code{NaN}, the return value is @code{NaN} and @code{errno} is set to
@code{EDOM}.  If @var{x} is a positive or negative @code{Inf}, the
return value is equal to the value of @var{x}, and @code{errno} is left
unchanged.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node asnprintf, asprintf, asinh, Alphabetical List
@unnumberedsec asnprintf
@c From file ./compat/stdio/asnprntf.txh
@findex asnprintf
@subheading Syntax

@example
#include <stdio.h>

char *asnprintf(char *buffer, size_t *np, const char *format, @dots{});
@end example

@subheading Description

Sends formatted output from the arguments (@dots{}) including
the terminating null byte to a string buffer and returns a pointer
to it.  This buffer can be preallocated and passed to the function
via @var{buffer}.  The buffer length must be passed by @var{np}.  The
function will write up to *@var{np} - 1 characters.  The *@var{np}th
character is used for the terminating nul.  Upon error, @code{errno}
is set and a @code{NULL} pointer is returned.

If @var{buffer} is a @code{NULL} pointer or *@var{np} is zero, a string
buffer is allocated and returned by the function on success.  If dynamic
allocation occurs, the preallocated buffer is left alone (with possibly
modified contents).  The length of the newly allocated string buffer is
returned by the function via the @var{np} pointer.  The allocated memory
must be returned to the heap with @code{free} (@pxref{free}). 

@subheading Return Value

If dynamic allocation occurs, a pointer to the newly allocated string buffer
is returned else @var{buffer}.  The number of characters that would have been
written (excluding the trailing nul) is returned by @var{np}; otherwise the
function returns a @code{NULL} pointer.

The maximum accepted value of *@var{np} is @code{INT_MAX}.  @code{INT_MAX} is
defined in @code{<limits.h>}.  A @code{NULL} pointer is returned and @code{errno}
is set to @code{EFBIG}, if *@var{np} is greater than this limit.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No (see note 1)
@item POSIX
@tab No
@end multitable

@noindent
Notes:

@enumerate
@item
The buffer size limit is imposed by DJGPP.  Other systems may not have this limitation.

@end enumerate

@subheading Example

@example
char *result;
char string[100];  /*  Preallocated buffer passed to asnprintf.  */
int len = 100;
long double pi = 3.1415926535897932384626433832795L;

result = asnprintf(string, &len, "Pi = %.15Lf\n", pi);

if (!result)
  printf("error: asnprintf failed.\n");
else
@{
  /*
   *  Your code using the buffer allocated by asnprintf.
   */
  do_something(result);
  if (result != string)
    free(result);  /*  Allocation had happened; release the buffer allocated by asnprintf.  */
@}
@end example
@c -----------------------------------------------------------------------------
@node asprintf, assert, asnprintf, Alphabetical List
@unnumberedsec asprintf
@c From file ./compat/stdio/asprintf.txh
@findex asprintf
@subheading Syntax

@example
#include <stdio.h>

int asprintf(char **bufferp, const char *format, @dots{});
@end example

@subheading Description

Sends formatted output from the arguments (@dots{}) including
the terminating null byte to the allocated buffer and returns
a pointer to it via the first parameter *@var{bufferp}.  This
memory must be returned to the heap with @code{free} (@pxref{free}). 
This function is analog of @code{sprintf()} (@pxref{sprintf}).

@subheading Return Value

The number of characters that would have been written (excluding
the terminating null byte) is returned; otherwise EOF is returned
to flag encoding or buffer space errors and the pointer
*@var{bufferp} is set to @code{NULL}.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char *strbuf;  /*  Pointer to the buffer allocated by asprintf.  */
int strlng;
long double pi = 3.1415926535897932384626433832795L;

strlng = asprintf(&strbuf, "Pi = %.15Lf\n", pi);

if (EOF == strlng)
  printf("error: asprintf failed.\n");
else
@{
  /*
   *  Your code using the buffer allocated by asprintf.
   */
  do_something(strbuf, strlng);

  free(strbuf);  /*  Release the buffer allocated by asprintf.  */
@}
@end example
@c -----------------------------------------------------------------------------
@node assert, atan, asprintf, Alphabetical List
@unnumberedsec assert
@c From file ./ansi/assert/assert.txh
@findex assert
@findex assertval
@subheading Syntax

@example
#define NDEBUG
#include <assert.h>

assert(expression);
assertval(expression);
@end example

@subheading Description

These macros are used to assist in debugging.  The source code includes
references to @code{assert} or @code{assertval}, passing them
expressions that should be @code{true} (non-zero).  When the expression
yields @code{false} (zero), a diagnostic message is printed to the
standard error stream, and the program aborts.

If you define the macro @code{NDEBUG} before including @file{assert.h},
then these @code{assert} and @code{assertval} expand to nothing to
reduce code size after debugging is done.

@subheading Return Value

@code{assert} returns 1 if its argument is non-zero, else it aborts.

@code{assertval} returns the value of its @var{expression} argument, if
non-zero, else it aborts.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99; (see note 1)
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 2)
@end multitable

@noindent
Notes:

@enumerate
@item
@code{assert} is ANSI, @code{assertval} is not.
@item
@code{assert} is Posix, @code{assertval} is not.
@end enumerate

@subheading Example

@example
/* Like `strdup', but doesn't crash if the argument is NULL.  */
char * safe_strdup(const char *s)
@{
  assert(s != 0);
  return strdup(s);
@}
@end example

@c -----------------------------------------------------------------------------
@node atan, atan2, assert, Alphabetical List
@unnumberedsec atan
@c From file ./ansi/math/atan.txh
@findex atan
@subheading Syntax

@example
#include <math.h>

double atan(double x);
@end example

@subheading Description

This function computes the angle, in the range @code{[-Pi/2..Pi/2]}
radians, whose tangent is @var{x}.

@subheading Return Value

The arc tangent, in radians, of @var{x}.  If @var{x} is a @code{NaN},
the return value is @code{NaN} and @code{errno} is set to @code{EDOM}.
If @var{x} is a positive or negative @code{Inf}, the return value is
equal to positive or negative @code{Pi/2}, respectively, and
@code{errno} is left unchanged.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node atan2, atanh, atan, Alphabetical List
@unnumberedsec atan2
@c From file ./ansi/math/atan2.txh
@findex atan2
@subheading Syntax

@example
#include <math.h>

double atan2(double y, double x);
@end example

@subheading Description

This function computes the angle, in the range @code{[-Pi..Pi]} radians,
whose tangent is @code{@var{y}/@var{x}}.  In other words, it computes
the angle, in radians, of the vector (@var{x},@var{y}) with respect to
the @code{+x} axis, reckoning the counterclockwise direction as
positive, and returning the value in the range @code{[-Pi, Pi]}.

@subheading Return Value

The arc tangent, in radians, of @code{@var{y}/@var{x}}.  @code{Pi} is
returned if @var{x} is negative and @var{y} is a negative zero,
@code{-0.0}.  @code{-Pi} is returned, if @var{x} is negative, and
@var{y} is a positive zero, @code{+0.0}.

If either @var{x} or @var{y} is infinite, @code{atan2} returns,
respectively, @code{Pi} with the sign of @var{y} or zero, and
@code{errno} is left unchanged.  However, if @emph{both} arguments are
infinite, the return value is @code{NaN} and @code{errno} is set to
@code{EDOM}.

A @code{NaN} is returned, and @code{errno} is set to @code{EDOM}, if
either @var{x} and @var{y} are both zero, or if either one of the
arguments is a @code{NaN}.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node atanh, atexit, atan2, Alphabetical List
@unnumberedsec atanh
@c From file ./ansi/math/atanh.txh
@findex atanh
@subheading Syntax

@example
#include <math.h>

double atanh(double x);
@end example

@subheading Description

This function computes the inverse hyperbolic tangent of @var{x}.

@subheading Return Value

The inverse hyperbolic tangent of @var{x}.  If the the value of
@var{x} is plus or minus 1, the return value is an @code{Inf} with the
same sign as the argument @var{x}, and @code{errno} is set to
@code{ERANGE}.  If the absolute value of @var{x} is greater than 1, the
return value is @code{NaN} and @code{errno} is set to @code{EDOM}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node atexit, atof, atanh, Alphabetical List
@unnumberedsec atexit
@c From file ./ansi/stdlib/atexit.txh
@findex atexit
@subheading Syntax

@example
#include <stdlib.h>

int atexit(void (*func)(void));
@end example

@subheading Description

This function places the specified function @var{func} on a list of
functions to be called when @code{exit} is called.  These functions are
called as if a last-in-first-out queue is used, that is, the last
function registered with @code{atexit} will be the first function called
by @code{exit}.

At least 32 functions can be registered this way.

@subheading Return Value

Zero on success, non-zero on error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
void exit_func()
@{
  remove("file.tmp");
@}

@dots{}
atexit(exit_func);
@dots{}
@end example

@c -----------------------------------------------------------------------------
@node atof, atoi, atexit, Alphabetical List
@unnumberedsec atof
@c From file ./ansi/stdlib/atof.txh
@findex atof
@subheading Syntax

@example
#include <stdlib.h>

double atof(const char *string);
@end example

@subheading Description

Convert as much of the string as possible to an equivalent double
precision real number. 

This function is almost like @code{strtod(string, NULL)} (@pxref{strtod}).

@subheading Return Value

The equivalent value, or zero if the string does not represent a number. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
main(int argc, char **argv)
@{
  double d = atof(argv[1]);
  @dots{}
@end example

@c -----------------------------------------------------------------------------
@node atoi, atol, atof, Alphabetical List
@unnumberedsec atoi
@c From file ./ansi/stdlib/atoi.txh
@findex atoi
@subheading Syntax

@example
#include <stdlib.h>

int atoi(const char *string);
@end example

@subheading Description

Convert as much of the string as possible to an equivalent integer
value.

This function is almost like @code{(int)strtol(string, NULL, 10)}
(@pxref{strtol}).

@subheading Return Value

The equivalent value, or zero if the string does not represent a number. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
main(int argc, char **argv)
@{
  int i = atoi(argv[1]);
  @dots{}
@end example

@c -----------------------------------------------------------------------------
@node atol, _atold, atoi, Alphabetical List
@unnumberedsec atol
@c From file ./ansi/stdlib/atol.txh
@findex atol
@subheading Syntax

@example
#include <stdlib.h>

long atol(const char *string);
@end example

@subheading Description

Convert as much of the string as possible to an equivalent long integer
value. 

This function is almost like @code{strtol(string, NULL, 10)}
(@pxref{strtol}).

@subheading Return Value

The equivalent value, or zero if the string does not represent a number. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
main(int argc, char **argv)
@{
  long l = atol(argv[1]);
  @dots{}
@end example

@c -----------------------------------------------------------------------------
@node _atold, atoll, atol, Alphabetical List
@unnumberedsec _atold
@c From file ./ansi/stdlib/atold.txh
@findex _atold
@subheading Syntax

@example
#include <stdlib.h>

long double _atold(const char *string);
@end example

@subheading Description

Convert as much of the string as possible to an equivalent long double
precision real number.

This function is almost like @code{_strtold(string, NULL)} (@pxref{_strtold}).

@subheading Return Value

The equivalent value, or zero if the string does not represent a number. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
main(int argc, char **argv)
@{
  long double d = _atold(argv[1]);
  @dots{}
@end example

@c -----------------------------------------------------------------------------
@node atoll, basename, _atold, Alphabetical List
@unnumberedsec atoll
@c From file ./ansi/stdlib/atoll.txh
@findex atoll
@subheading Syntax

@example
#include <stdlib.h>

long long int atoll(const char *string);
@end example

@subheading Description

Convert as much of the string as possible to an equivalent long long
integer value.

This function is almost like @code{strtoll(string, NULL, 10)}
(@pxref{strtoll}).

@subheading Return Value

The equivalent value, or zero if the string does not represent a number.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable


@subheading Example

@example
main(int argc, char **argv)
@{
  long long int l = atoll(argv[1]);
  @dots{}
@}
@end example
@c -----------------------------------------------------------------------------
@node basename, bcmp, atoll, Alphabetical List
@unnumberedsec basename
@c From file ./compat/unistd/basename.txh
@findex basename
@subheading Syntax

@example
#include <unistd.h>

char * basename (const char *fname);
@end example

@subheading Description

This function returns the @dfn{basename} of the file, which is the last
part of its full name given by @var{fname}, with the drive letter and
leading directories stripped off.  For example, the basename of
@code{c:/foo/bar/file.ext} is @code{file.ext}, and the basename of
@code{a:foo} is @code{foo}.  Trailing slashes and backslashes are
significant: the basename of @code{c:/foo/bar/} is an empty string after
the rightmost slash.

This function treats both forward- and backslashes like directory
separators, so it can handle file names with mixed styles of slashes.

@subheading Return Value

A pointer into the original file name where the basename starts.  Note
that this is @strong{not} a new buffer allocated with @code{malloc}.  If
@var{fname} is a NULL pointer, the function will return a NULL pointer.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  if (strcmp (basename (file_name), "gcc.exe") == 0)
    printf ("The file %s is the GNU C/C++ compiler\n", file_name);
@end example

@c -----------------------------------------------------------------------------
@node bcmp, bcopy, basename, Alphabetical List
@unnumberedsec bcmp
@c From file ./compat/bsd/bcmp.txh
@findex bcmp
@subheading Syntax

@example
#include <string.h>

int bcmp(const void *ptr1, const void *ptr2, int length);
@end example

@subheading Description

Compare memory pointed to by @var{ptr1} and @var{ptr2} for at most
@var{length} bytes. 

@subheading Return Value

The number of bytes remaining when the first mismatch occurred, or zero
if all bytes were equal. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
void f(char *s1, char *s2)
@{
  int l = bcmp(s1, s2, strlen(s1));
  printf("Difference: %s, %s\n", s1+strlen(s1)-l, s2+strlen(s1)-l);
@}

@end example

@c -----------------------------------------------------------------------------
@node bcopy, bdos, bcmp, Alphabetical List
@unnumberedsec bcopy
@c From file ./compat/bsd/bcopy.txh
@findex bcopy
@subheading Syntax

@example
#include <string.h>

void bcopy(const void *source, void *dest, int length);
@end example

@subheading Description

Copy @var{length} bytes from @var{source} to @var{dest}.  Overlapping
regions are handled properly, although this behavior is not portable. 

@subheading Return Value

No value is returned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
struct s a, b;
bcopy(a, b, sizeof(struct s));
@end example

@c -----------------------------------------------------------------------------
@node bdos, bdosptr, bcopy, Alphabetical List
@unnumberedsec bdos
@c From file ./dos/dos/bdos.txh
@findex bdos
@subheading Syntax

@example
#include <dos.h>

int bdos(int func, unsigned dx, unsigned al);
@end example

@subheading Description

Calls function @var{func} of the software interrupt 0x21, passing it
@var{al} as the subfunction and (the lower 16 bit of) @var{dx} in the
@code{DX} register.  This function will only work for a subset of DOS
functions which require no arguments at all, or take non-pointer arguments
in the @code{AL} and @code{DX} registers only.  For functions which
require a pointer in the @code{DX} register, use @code{bdosptr}
(@pxref{bdosptr}).

@subheading Return Value

Whatever the called function returns in the AX register.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
/* read a character */
int ch = bdos(1, 0, 0) & 0xff;
@end example

@c -----------------------------------------------------------------------------
@node bdosptr, _bios_disk, bdos, Alphabetical List
@unnumberedsec bdosptr
@c From file ./dos/dos/bdos.txh
@findex bdosptr
@subheading Syntax

@example
#include <dos.h>

int bdosptr(int func, void *ptr, unsigned al);
@end example

@subheading Description

Calls function @var{func} of the software interrupt 0x21, passing it
@var{al} as the subfunction and a pointer to a copy of the buffer contents
whose address is in @var{ptr} through the @code{DX} register.  This
function will only work for a subset of DOS which require an argument
in the @code{AL} register and a pointer in @code{DX} register.  For
functions which require non-pointer arguments in the @code{DX} register,
use @code{bdos} (@pxref{bdos}).  To make the contents of @var{ptr}
available to DOS, @code{bdosptr} copies it to the transfer buffer located
in the low (below 1 Meg mark) memory.

Currently, some of the functions which take a pointer to a buffer in
@code{DX} are @emph{NOT} supported (notably, most of the FCB-based
functions).  @xref{int86}, for the list of supported functions.

@subheading Return Value

Whatever the called function returns in the AX register.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
/* print a string */
bdosptr(9, "Hello, there$", 0);
@end example

@c -----------------------------------------------------------------------------
@node _bios_disk, _bios_equiplist, bdosptr, Alphabetical List
@unnumberedsec _bios_disk
@c From file ./bios/b_disk.txh
@findex _bios_disk
@tindex diskinfo_t@r{ structure}
@subheading Syntax

@example
#include <bios.h>

unsigned _bios_disk(unsigned cmd, struct diskinfo_t *di)
@end example

@subheading Description

This function interfaces with the BIOS disk service (interrupt 0x13).
The parameter @var{cmd} select the corresponding disk service and
the structure @var{di} holds the disk parameters.

@example
struct diskinfo_t @{
  unsigned drive;       /* Drive number. */
  unsigned head;        /* Head number. */
  unsigned track;       /* Track number. */
  unsigned sector;      /* Sector number. (1-63) */
  unsigned nsectors;    /* Number of sectors to read/write/verify. */
  void    *buffer;      /* Buffer for reading/writing/verifying. */
@}
@end example

The following services are available based on value of @var{cmd}:

@table @code

@item _DISK_RESET

Forces the disk controller to do a hard reset, preparing for floppy-disk
I/O. This is useful after an error occurs in another operation, such
as a read. If this service is specified, the @var{di} argument is
ignored. Status is returned in the 8 high-order bits (AH) of the return
value. If there is an error, the high-order byte will contain a set of
status flags, as defined below under Return Value.

@item _DISK_STATUS

Obtains the status of the last disk operation. If this service is specified,
the <diskinfo> argument is ignored. Status is returned in the 8 low-order bits
(AL) of the return value. If there is an error, the low-order byte (AL) will
contain a set of status flags, as defined below under Return Value.

@item _DISK_READ

Reads one or more disk sectors into memory. This service uses all fields
of the structure pointed to by @var{diskinfo}. If no error occurs, the
function returns 0 in the high-order byte and the number of sectors read
in the low-order byte. If there is an error, the high-order byte (AH) will
contain a set of status flags, as defined below under Return Value.

@item _DISK_WRITE

Writes data from memory to one or more disk sectors. This service uses
all fields of the structure pointed to by <diskinfo>. If no error occurs,
the function returns 0 in the high-order byte (AH) and the number of
sectors written in the low-order byte (AL). If there is an error,
the high-order byte will contain a set of status flags, as defined below
under Return Value.

@item _DISK_FORMAT

Formats the track specified by @var{diskinfo}. The @var{head} and @var{track}
fields indicate the track to format. Only one track can be formatted
in a single call. The @var{buffer} field points to a set of sector markers.
The format of the markers depends on the type of disk drive (see a technical
reference to the PC BIOS to determine the marker format). The high-order
byte (AH) of the return value contains the status of the call; 0 equals
success. If there is an error, the high-order byte will contain a set of
status flags, as defined below under Return Value.

@item _DISK_VERIFY

Checks the disk to be sure the specified sectors exist and can be read.
It also runs a CRC (cyclic redundancy check) test. This service uses all
fields (except @var{buffer}) of the structure pointed to by @var{diskinfo}.
If no error occurs, the function returns 0 in the high-order byte (AH)
and the number of sectors compared in the low-order byte (AL), as defined
below under Return Value.

@end table

@subheading Return Value

Return value of AX register. The meaning of high-order byte (AH):
@example
0x00  No error
0x01  Invalid request or a bad command
0x02  Address mark not found
0x03  Disk write protected
0x04  Sector not found
0x05  Reset failed
0x06  Floppy disk removed
0x07  Drive parameter activity failed
0x08  Direct Memory Access (DMA) overrun
0x09  DMA crossed 64K boundary
0x0A  Bad sector flag detected
0x0B  Bad track flag detected
0x0C  Media type not found
0x0D  Invalid number of sectors on format
0x0E  Control data access mark detected
0x0F  DMA arbitration level out of range
0x10  Data read (CRC or ECC) error
0x11  Corrected data read (ECC) error
0x20  Controller failure
0x40  Seek error
0x80  Disk timed out or failed to respond
0xAA  Drive not ready
0xBB  Undefined error
0xCC  Write fault on drive
0xE0  Status error
0xFF  Sense operation failed
@end example

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char record_buffer[512];
struct diskinfo_t di;

di.drive    = 0x80;
di.head     = 0;
di.track    = 0;
di.sector   = 1;
di.nsectors = 1;
di.buffer   = &record_buffer;
if ( _bios_disk(_DISK_READ, &di) )
  puts("Disk error.");
@end example
@c -----------------------------------------------------------------------------
@node _bios_equiplist, _bios_keybrd, _bios_disk, Alphabetical List
@unnumberedsec _bios_equiplist
@c From file ./bios/b_equip.txh
@findex _bios_equiplist
@subheading Syntax

@example
#include <bios.h>

unsigned _bios_equiplist(void)
@end example

@subheading Description

This function returns the equipment word from BIOS request 0x11.  The
bits correspond to the following values:

@example
Bits  Meaning
0     True (1) if disk drive(s) installed
1     True (1) if math coprocessor installed
2-3   System RAM in 16K blocks (16-64K)
4-5   Initial video mode:
           00 = Reserved
           01 = 40 x 25 color
           10 = 80 x 25 color
           11 = 80 x 25 monochrome
6-7   Number of floppy-disk drives installed
      (00 = 1, 01 = 2, etc.)
8     False (0) if and only if a Direct Memory Access (DMA)
      chip is installed
9-11  Number of RS232 serial ports installed
12    True (1) if and only if a game adapter is installed
13    True (1) if and only if an internal modem is installed
14-15 Number of printers installed
@end example

@subheading Return Value

The equipment word.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
if ( _bios_equiplist() & 0xc000 )
  do_printing();
@end example
@c -----------------------------------------------------------------------------
@node _bios_keybrd, _bios_memsize, _bios_equiplist, Alphabetical List
@unnumberedsec _bios_keybrd
@c From file ./bios/b_key.txh
@findex _bios_keybrd
@subheading Syntax

@example
#include <bios.h>

unsigned _bios_keybrd(unsigned cmd);
@end example

@subheading Description

The @code{_bios_keybrd} function uses INT 0x16 to access the keyboard
services.  The @var{cmd} argument can be any of the following manifest
constants:

@table @code

@item _KEYBRD_READ
read the next key pressed.

@item _NKEYBRD_READ
read the next extended key pressed.  Unlike @code{_KEYBRD_READ}, this
command knows about keys introduced with the AT-style 101-key keyboards,
such as @key{F11} and @key{F12}, and can distinguish between the editing
keys on the numeric pad and the grey keys of the edit pad.  On the other
hand, some of the extended keys return two-byte sequences which
typically begin with the @code{E0h} (224 decimal) prefix, so code that
uses @code{_NKEYBRD_READ} should deal with this complexity.

@item _KEYBRD_READY
check if a key is waiting in the keyboard buffer.

@item _NKEYBRD_READY
check if an extended key is waiting in the keyboard buffer.  Like
@code{_KEYBRD_READY}, but recognizes extended keys such as @key{F12},
which @code{_KEYBRD_READY} ignores.

@item _KEYBRD_SHIFTSTATUS
read keyboard shift state (the byte at the address @code{40h:17h} in the
BIOS data area):

@example
7654 3210  Meaning
---- ---X  Right SHIFT is pressed
---- --X-  Left SHIFT is pressed
---- -X--  CTRL is pressed
---- X---  ALT is pressed
---X ----  Scroll Lock locked
--X- ----  Num Lock locked
-X-- ----  Caps Lock locked
X--- ----  Insert locked
@end example

@item _NKEYBRD_SHIFTSTATUS
read keyboard shift and extended shift state (the byte at the address
@code{40h:17h} in the BIOS data area combined with the extended shift
flags from the bytes at addresses @code{40h:18h} and @code{40h:96h}):

@example
FEDC BA98  7654 3210  Meaning
---- ----  ---- ---X  Right SHIFT is pressed
---- ----  ---- --X-  Left SHIFT is pressed
---- ----  ---- -X--  CTRL is pressed
---- ----  ---- X---  ALT is pressed
---- ----  ---X ----  Scroll Lock locked
---- ----  --X- ----  Num Lock locked
---- ----  -X-- ----  Caps Lock locked
---- ----  X--- ----  Insert locked

---- ---X  ---- ----  Left CTRL is pressed
---- --X-  ---- ----  Left ALT is pressed
---- -X--  ---- ----  Right CTRL is pressed
---- X---  ---- ----  Right ALT is pressed
---X ----  ---- ----  Scroll Lock is pressed
--X- ----  ---- ----  Num Lock is pressed
-X-- ----  ---- ----  Caps Lock is pressed
X--- ----  ---- ----  SysReq is pressed
@end example

@end table

Return Value

With the @code{*_READ} and @code{*_SHIFTSTATUS} arguments, the
@code{_bios_keybrd} function returns the contents of the @sc{ax}
register after the BIOS call.  For the @code{*_READ} arguments, this is
the combination of scan code and ASCII code for alphanumeric keys, or a
scan code and either zero or the @code{E0h} prefix for special keys.

With the @code{*_READY} arguments, @code{_bios_keybrd} returns 0 if no
key is waiting in the BIOS keyboard buffer.  If there is a key,
@code{_bios_keybrd} returns the key waiting to be read (that is, the
same value as the corresponding @code{*_READ} would return).

With the @code{*_READ} and @code{*_READY} arguments, the
@code{_bios_keybrd} function returns -1 if @kbd{Ctrl+@key{BREAK}} has
been pressed and is the next keystroke to be read.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
while( !_bios_keybrd(_KEYBRD_READY) )
  try_to_do_something();
@end example
@c -----------------------------------------------------------------------------
@node _bios_memsize, _bios_printer, _bios_keybrd, Alphabetical List
@unnumberedsec _bios_memsize
@c From file ./bios/b_memsiz.txh
@findex _bios_memsize
@subheading Syntax

@example
#include <bios.h>

unsigned _bios_memsize(void);
@end example

@subheading Description

This function returns the amount of system memory in 1K blocks (up to
640K).

@subheading Return Value

Size of memory (in K).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
printf("This system has %d bytes of memory\n", _bios_memsize() * 1024);
@end example
@c -----------------------------------------------------------------------------
@node _bios_printer, _bios_serialcom, _bios_memsize, Alphabetical List
@unnumberedsec _bios_printer
@c From file ./bios/b_print.txh
@findex _bios_printer
@subheading Syntax

@example
#include <bios.h>

unsigned _bios_printer(unsigned cmd, unsigned printer, unsigned data);
@end example

@subheading Description
The _bios_printer routine uses INT 0x17 to perform printer output
services for parallel printers. The @var{printer} argument specifies
the affected printer, where 0 is LPT1, 1 is LPT2, and so on.
The @var{cmd} argument can be any of the following manifest
constants:

@table @code

@item _PRINTER_INIT

@item Reset and initialize the specified printer port

@item _PRINTER_STATUS

Return the status of the specified printer port

@item _PRINTER_WRITE

Print the @var{data} argument to the specified printer port

@end table

@subheading Return Value

The _bios_printer function returns the value in the AX register
after the BIOS interrupt. The high-order byte (AH) of the return
value indicates the printer status after the operation, as defined
below:

@example
Bit     Meaning if True

0       Printer timed out
1       Not used
2       Not used
3       I/O error
4       Printer selected
5       Out of paper
6       Acknowledge
7       Printer not busy
@end example

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
while (*c)
  _bios_printer(_PRINTER_WRITE, *c++, 0);
@end example
@c -----------------------------------------------------------------------------
@node _bios_serialcom, _bios_timeofday, _bios_printer, Alphabetical List
@unnumberedsec _bios_serialcom
@c From file ./bios/b_com.txh
@findex _bios_serialcom
@subheading Syntax

@example
#include <bios.h>

unsigned _bios_serialcom(unsigned cmd, unsigned serialport,
                         unsigned data);
@end example

@subheading Description

The _bios_serialcom routine uses INT 0x14 to provide serial
communications services. The @var{serialport} argument is set to 0
for COM1, to 1 for COM2, and so on. The @var{cmd} argument can be
set to one of the following manifest constants:

@table @code

@item _COM_INIT

Initialize com port (@var{data} is the settings)

@item _COM_RECEIVE

Read a byte from port

@item _COM_SEND

Write a byte to port

@item _COM_STATUS

Get the port status

@end table

The @var{data} argument is ignored if @var{cmd} is set to
_COM_RECEIVE or _COM_STATUS. The @var{data} argument for
_COM_INIT is created by combining one or more of the following
constants (with the OR operator):

@example
_COM_CHR7         7 bits/character
_COM_CHR8         8 bits/character
_COM_STOP1        1 stop bit
_COM_STOP2        2 stop bits
_COM_NOPARITY     no parity
_COM_EVENPARITY   even parity
_COM_ODDPARITY    odd parity
_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
@end example

The default value of @var{data} is 1 stop bit, no parity, and 110
baud.

@subheading Return Value

The function returns a 16-bit integer whose high-order byte
contains status bits. The meaning of the low-order byte varies,
depending on the @var{cmd} value. The high-order bits are as
follows:

@example
Bit     Meaning if Set

15      Timed out
14      Transmission-shift register empty
13      Transmission-hold register empty
12      Break detected
11      Framing error
10      Parity error
 9      Overrun error
 8      Data ready
@end example

When service is _COM_SEND, bit 15 is set if data cannot be sent.

When service is _COM_RECEIVE, the byte read is returned in the
low-order bits if the call is successful. If an error occurs, any
of the bits 9, 10, 11, or 15 is set.

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

@example
Bit     Meaning if Set

7       Receive-line signal detected
6       Ring indicator
5       Data-set-ready
4       Clear-to-send
3       Change in receive-line signal detected
2       Trailing-edge ring indicator
1       Change in data-set-ready status
0       Change in clear-to-send status
@end example

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
/* 9600 baud, no parity, one stop, 8 bits */
_bios_serialcom(_COM_INIT, 0,
                _COM_9600|_COM_NOPARITY|_COM_STOP1|_COM_CHR8);
for(i=0; buf[i]; i++)
  _bios_serialcom(_COM_SEND, 0, buf[i]);
@end example
@c -----------------------------------------------------------------------------
@node _bios_timeofday, bioscom, _bios_serialcom, Alphabetical List
@unnumberedsec _bios_timeofday
@c From file ./bios/b_time.txh
@findex _bios_timeofday
@subheading Syntax

@example
#include <bios.h>

unsigned _bios_timeofday(unsigned cmd, unsigned long *timeval);
@end example

@subheading Description

The _bios_timeofday routine uses INT 0x1A to get or set the clock
count (which is the number of 18.2 Hz ticks since midnight). The
@var{cmd} argument can be either the _TIME_GETCLOCK or _TIME_SETCLOCK
manifest constant.

@subheading Return Value

If the argument is _TIME_GETCLOCK, the routine returns a nonzero
value if midnight was passed since last read, or zero if midnight
was not passed. If the argument is _TIME_SETCLOCK, the return
value is undefined.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
unsigned hour, min, sec, hsec;
unsigned long ticks;
...
ticks = (unsigned long)(hour * 65543.33) + (min * 1092.38) +
        (sec * 18.21) + (hsec * 0.182);
_bios_timeofday(_TIME_SETCLOCK, &ticks);
@end example
@c -----------------------------------------------------------------------------
@node bioscom, biosdisk, _bios_timeofday, Alphabetical List
@unnumberedsec bioscom
@c From file ./bios/bioscom.txh
@findex bioscom
@subheading Syntax

@example
#include <bios.h>

int bioscom(int cmd, char data, int port);
@end example

@subheading Description

This function accesses the BIOS interrupt 0x14 function, serial
communication services.  @code{port} should be the COM port (0=COM1,
1=COM2, etc).

The valid values of cmd are:

@table @asis
@item 0 - initialize com port (@var{data} is the settings)
@item 1 - write byte to port
@item 2 - read byte from port (@var{data} is ignored)
@item 3 - get port status
@end table

For initialization, the byte is made up of the following bits:

@example
0000 0000
7654 3210  Meaning

---- --10  7 bits/character
---- --11  8 bits/character
---- -0--  1 stop bit
---- -1--  2 stop bits
---X 0---  no parity
---0 1---  odd parity
---1 1---  even parity
000- ----  110 baud
001- ----  150 baud
010- ----  300 baud
011- ----  600 baud
100- ----  1200 baud
101- ----  2400 baud
110- ----  4800 baud
111- ----  9600 baud
@end example

For writing a character out to the port, the return value's lower
8 bits contain the same byte as passed as the @var{data} argument.

For reading a character from the port, the value of @var{data} is
ignored, and the lower 8 bits of the return value contain the byte
read.  Also, the "timeout" bit in the upper 8 bits is used as an error
indicator in this case (0=success, 1=error).  If it indicates an
error, you should call the "get port status" variant to get the
detailed error bits.

@subheading Return Value

The return value is a sequence of bits that indicate the port status
and, for cmd=0 and 3, the modem status.  For read/write operations,
the lower eight bits are the character read.

@example
1111 1100 0000 0000
5432 1098 7654 3210  Meaning

---- ---- ---- ---1  CTS change
---- ---- ---- --1-  DSR change
---- ---- ---- -1--  ring change
---- ---- ---- 1---  carrier detect change
---- ---- ---1 ----  CTS present
---- ---- --1- ----  DSR present
---- ---- -1-- ----  ring present
---- ---- 1--- ----  carrier detect
---- ---1 ---- ----  data ready
---- --1- ---- ----  overrun error
---- -1-- ---- ----  parity error
---- 1--- ---- ----  framing error
---1 ---- ---- ----  break detected
--1- ---- ---- ----  transmit holding register empty
-1-- ---- ---- ----  transmit shift register empty
1--- ---- ---- ----  time out (=1 if error present for cmd=1,2)
@end example

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
bioscom(0, 0xe3, 0); /* 9600 baud, no parity, one stop, 8 bits */
for (i=0; buf[i]; i++)
  bioscom(1, buf[i], 0);
@end example

@c -----------------------------------------------------------------------------
@node biosdisk, biosequip, bioscom, Alphabetical List
@unnumberedsec biosdisk
@c From file ./bios/biosdisk.txh
@findex biosdisk
@subheading Syntax

@example
#include <bios.h>

int biosdisk(int cmd, int drive, int head, int track,
	     int sector, int nsects, void *buffer);
@end example

@subheading Description

This function interfaces with the BIOS disk service (interrupt 0x13).
Please refer to a BIOS reference manual for detailed information about
the parameters of this call.  The function assumes a sector size of 512
bytes.

The following functions of Int 13h are currently supported:

@table @asis
@item 0 - reset disk subsystem
@item 1 - get status of last operation (see @ref{_bios_disk}, for possible values)
@item 2 - read one or more sectors
@item 3 - write one or more sectors
@item 5 - format a track
@item 6 - format a cylinder and set bad sector flag
@item 7 - format drive from specified cylinder
@item 8 - get drive parameters
@item 9 - initialize drive parameters
@item 10 - read long sectors
@item 11 - write long sectors
@item 12 - seek to cylinder
@item 13 - alternate fixed disk reset
@item 14 - read sector buffer
@item 15 - write sector buffer
@item 16 - test for drive ready
@item 17 - recalibrate drive
@item 18 - controller RAM diagnostic
@item 19 - controller drive diagnostic
@item 20 - controller internal diagnostic
@item 21 - get DASD type
@item 22 - read disk change line status
@item 23 - set DASD type (pass DASD code in @var{nsects})
@item 24 - set media type for format
@end table

The first request with more sectors than will fit in the transfer
buffer will cause a DOS buffer to be allocated.  This buffer is
automatically freed when your application exits.  Requests for more
sectors than 18 sectors (9K) will fail.

Function 8 returns values in @var{buffer} as follows:

@table @asis
@item byte 0 = sectors per track (bits 0..5), top two bits of cylinder (in bits 6..7)
@item byte 1 = cylinders (bits 0..7)
@item byte 2 = number of drives
@item byte 3 = number of heads
@end table

@subheading Return Value

The value of AH returned by the BIOS.  See @ref{_bios_disk}, for a
detailed list of possible status and error codes.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char buffer[512];
if (biosdisk(2, 0x80, 0, 0, 0, 1, buffer))
  error("disk");
@end example

@c -----------------------------------------------------------------------------
@node biosequip, bioskey, biosdisk, Alphabetical List
@unnumberedsec biosequip
@c From file ./bios/biosequi.txh
@findex biosequip
@subheading Syntax

@example
#include <bios.h>

int biosequip(void);
@end example

@subheading Description

This function returns the equipment word from BIOS request 0x11.  The
bits correspond to the following values:

@example
1111 1100 0000 0000
5432 1098 7654 3210  Meaning

---- ---- ---- ---X  1 = disk drive(s) installed
---- ---- ---- --X-  1 = math coprocessor installed
---- ---- ---- XX--  System memory: 00=16k, 01=32k, 10=48k,
                                    11=64k (non PS/2)
---- ---- ---- -X--  1 = pointing device installed (PS/2)
---- ---- ---- X---  not used on PS/2
---- ---- --XX ----  initial video mode: 01=CO40 10=CO80 11=MONO
---- ---- XX-- ----  disk drives 00=1 01=2 10=3 11=4 (zero if bit 1=0)
---- ---X ---- ----  1 = no DMA available
---- XXX- ---- ----  number of serial ports installed (000=0 001=1 etc)
---X ---- ---- ----  1 = game port adapter installed
--X- ---- ---- ----  1 = internal modem installed (PS/2)
--X- ---- ---- ----  1 = serial printer attached (non PS/2)
XX-- ---- ---- ----  number of printers installed (00=0 01=1 10=2 11=3)
@end example

@subheading Return Value

The equipment word.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
if (biosequip() & 0xc000)
  do_printing();
@end example

@c -----------------------------------------------------------------------------
@node bioskey, biosmemory, biosequip, Alphabetical List
@unnumberedsec bioskey
@c From file ./bios/bioskey.txh
@findex bioskey
@subheading Syntax

@example
#include <bios.h>

int bioskey(int command)
@end example

@subheading Description

This function issues the BIOS keyboard interrupt 16h with @var{command}
in the @sc{ah} register, and returns the results of that call.  The
argument @var{command} can accept the following values:

@table @asis

@item @var{command} = 00h

Returns the next key pressed.  The value returned is a combination of
the key's scan code in the high 8 bits and its ASCII code in the low 8
bits.  For non-alphanumeric keys, such as the arrow keys, the low 8
bits are zeroed.

@item @var{command} = 01h

Checks the keyboard, returns zero if no key pressed, else the key.  Does
not dequeue the key from the keyboard buffer.  The value returned when a
key was pressed is a combination of the key's scan code in the high 8
bits and either its ASCII code or zero in the low 8 bits.

If the @kbd{Ctrl-@key{BREAK}} key was pressed, returns -1.

@item @var{command} = 02h

Returns the keyboard shift state:

@example
7654 3210  Meaning

---- ---X  Right shift key down
---- --X-  Left shift key down
---- -X--  Ctrl key down
---- X---  Alt key down
---X ----  Scroll lock on
--X- ----  Num lock on
-X-- ----  Caps lock on
X--- ----  Insert on
@end example

@item @var{command} = 10h

Returns the next extended key pressed.  This works like the case of
@var{command} = 0, but it recognizes additional keys from the AT-style
extended 101-key keyboard, like the second @key{Alt} key and @key{F12}.
If a key was pressed, returns the scan code and ASCII code packed in
same way as for @var{command} = 0, except that the extended keys have
the @code{E0h} prefix in the low 8 bits.

Almost every PC nowadays has an extended 101-key keyboard.

@item @var{command} = 11h

Like the case of @var{command} = 1, but recognizes the additional keys
of the extended keyboard.

@item @var{command} = 12h

Returns the two status bytes of the enhanced keyboard, packed in the low
16 bits of the return value.  The individual bits of the return value
are defined in the following table:

@example
FEDC BA98  7654 3210  Meaning
---- ----  ---- ---X  Right SHIFT is pressed
---- ----  ---- --X-  Left SHIFT is pressed
---- ----  ---- -X--  CTRL is pressed
---- ----  ---- X---  ALT is pressed
---- ----  ---X ----  Scroll Lock locked
---- ----  --X- ----  Num Lock locked
---- ----  -X-- ----  Caps Lock locked
---- ----  X--- ----  Insert locked

---- ---X  ---- ----  Left CTRL is pressed
---- --X-  ---- ----  Left ALT is pressed
---- -X--  ---- ----  Right CTRL is pressed
---- X---  ---- ----  Right ALT is pressed
---X ----  ---- ----  Scroll Lock is pressed
--X- ----  ---- ----  Num Lock is pressed
-X-- ----  ---- ----  Caps Lock is pressed
X--- ----  ---- ----  SysReq is pressed
@end example

@end table

@subheading Return Value

Depends on @var{command}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
while (!bioskey(1))
  do_stuff();
@end example

@c -----------------------------------------------------------------------------
@node biosmemory, biosprint, bioskey, Alphabetical List
@unnumberedsec biosmemory
@c From file ./bios/biosmem.txh
@findex biosmemory
@subheading Syntax

@example
#include <bios.h>

unsigned biosmemory(void);
@end example

@subheading Description

This function returns the amount of system memory in 1k blocks.

Note that this function doesn't know about extended memory above the
640K mark, so it will report 640K at most.  This is a limitation of the
BIOS.

@subheading Return Value

Bytes of memory / 1024.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
printf("This system has %d bytes of memory\n", biosmemory()*1024);
@end example

@c -----------------------------------------------------------------------------
@node biosprint, biostime, biosmemory, Alphabetical List
@unnumberedsec biosprint
@c From file ./bios/biosprin.txh
@findex biosprint
@subheading Syntax

@example
#include <bios.h>

int biosprint(int cmd, int byte, int port)
@end example

@subheading Description

@table @asis

@item @var{command} = 0

@code{byte} is sent to parallel port @var{port}.

@item @var{command} = 1

Parallel port @var{port} is reset and initialized.

@item @var{command} = 2

The status of parallel port @var{port} is returned.

@example
7654 3210  Meaning

---- ---X  Timeout
---- -XX-  Unused
---- X---  I/O Error
---X ----  Selected
--X- ----  Out of paper
-X-- ----  Acknowledged
X--- ----  Idle
@end example

@end table

@subheading Return Value

The printer status.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
while (*c)
  biosprint(0, *c++, 0);
@end example

@c -----------------------------------------------------------------------------
@node biostime, blinkvideo, biosprint, Alphabetical List
@unnumberedsec biostime
@c From file ./bios/biostime.txh
@findex biostime
@subheading Syntax

@example
#include <bios.h>

long biostime(int cmd, long newtime);
@end example

@subheading Description

This function reads (@var{cmd}=0) or sets (@var{cmd}=1) the internal
tick counter, which is the number of 18.2 Hz ticks since midnight.

@subheading Return Value

When reading, the number of ticks since midnight.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
long ticks = biostime(0, 0);
@end example

@c -----------------------------------------------------------------------------
@node blinkvideo, brk, biostime, Alphabetical List
@unnumberedsec blinkvideo
@c From file ./pc_hw/co80/conio.txh
@findex blinkvideo

@subheading Syntax

@example
#include <conio.h>

void blinkvideo(void);
@end example

@subheading Description

Bit 7 (@samp{MSB}) of the character attribute byte has two possible
effects on EGA and VGA displays: it can either make the character blink
or change the background color to bright (thus allowing for 16
background colors as opposed to the usual 8).  This function sets that
bit to display blinking characters.  After a call to this function,
every character written to the screen with bit 7 of the attribute byte
set, will blink.  The companion function @code{intensevideo}
(@pxref{intensevideo}) has the opposite effect.

Note that there is no BIOS function to get the current status of this
bit, but bit 5 of the byte at @code{0040h:0065h} in the BIOS area
indicates the current state: if it's 1 (the default), blinking
characters will be displayed.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node brk, bsearch, blinkvideo, Alphabetical List
@unnumberedsec brk
@c From file ./crt0/crt0.txh
@findex brk
@subheading Syntax

@example
#include <unistd.h>

int brk(void *ptr);
@end example

@subheading Description

This function changes the @emph{break} for the program.  This is the
first address that, if referenced, will cause a fault to occur.  The
program asks for more memory by specifying larger values for @var{ptr}. 
Normally, this is done transparently through the @code{malloc} function. 

@subheading Return Value

Zero if the break was changed, -1 if not.  @code{errno} is set to the
error. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
if (brk(old_brk+1000))
  printf("no memory\n");
@end example

@c -----------------------------------------------------------------------------
@node bsearch, bzero, brk, Alphabetical List
@unnumberedsec bsearch
@c From file ./ansi/stdlib/bsearch.txh
@findex bsearch
@subheading Syntax

@example
#include <stdlib.h>

void *bsearch (const void *key, const void *base, size_t num, 
  size_t size, int (*ptf)(const void *ckey, const void *celem));
@end example

@subheading Description

Given an array of values, perform a binary search on the values looking
for value that "matches" the given key.  A match is determined by
calling the provided function @var{ptf} and passing it the key as
@var{ckey} and a pointer to one of the elements of the array as
@var{celem}.  This function must return a negative number if the key is
closer than the element to the beginning of the array, positive if
it is closer to the end, and zero if the element matches the key.

The array begins at address @var{base} and contains @var{num} elements,
each of size @var{size}. 

@subheading Return Value

Returns a pointer to the element that matches the key, else @var{NULL}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
typedef struct @{
  int a, b;
@} q;

int compare(void *key, void *elem)
@{
  return *(int *)key - ((q *)elem)->a;
@}

q qlist[100];

@dots{}
q *match = bsearch(4, qlist, 100, sizeof(q), compare);
printf("4->%d=n", match->b);
@dots{}

@end example

@c -----------------------------------------------------------------------------
@node bzero, calloc, bsearch, Alphabetical List
@unnumberedsec bzero
@c From file ./compat/bsd/bzero.txh
@findex bzero
@subheading Syntax

@example
#include <string.h>

void bzero(void *pointer, int length);
@end example

@subheading Description

The data at @var{pointer} is filled with @var{length} zeros. 

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char foo[100];
bzero(foo,100);
@end example

@c -----------------------------------------------------------------------------
@node calloc, cbrt, bzero, Alphabetical List
@unnumberedsec calloc
@c From file ./ansi/stdlib/calloc.txh
@findex calloc
@subheading Syntax

@example
#include <stdlib.h>

void *calloc(size_t num_elements, size_t size);
@end example

@subheading Description

This function allocates enough memory for @var{num_elements} objects of
size @var{size}.  The memory returned is initialized to all zeros.  The
pointer returned should later be passed to free (@pxref{free}) so that
the memory can be returned to the heap.

You may use cfree (@pxref{cfree}) to free the pointer also; it just
calls free.

@subheading Return Value

A pointer to the memory, or @code{NULL} if no more memory is available.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
Complex *x = calloc(12, sizeof(Complex));
cfree(x);
@end example

@c -----------------------------------------------------------------------------
@node cbrt, ceil, calloc, Alphabetical List
@unnumberedsec cbrt
@c From file ./compat/math/cbrt.txh
@findex cbrt
@subheading Syntax

@example
#include <math.h>

double cbrt(double x);
@end example

@subheading Description

This function computes the cube root of @var{x}.  It is faster and more
accurate to call @code{cbrt(@var{x})} than to call
@w{@code{pow(@var{x}, 1./3.)}}.

@subheading Return Value

The cube root of @var{x}.  If the value of @var{x} is @code{NaN}, the
return value is @code{NaN} and @code{errno} is set to @code{EDOM}.
Infinite arguments are returned unchanged, without setting
@code{errno}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable

@c -----------------------------------------------------------------------------
@node ceil, cfgetispeed, cbrt, Alphabetical List
@unnumberedsec ceil
@c From file ./ansi/math/ceil.txh
@findex ceil
@subheading Syntax

@example
#include <math.h>

double ceil(double x);
@end example

@subheading Description

This function computes the smallest integer greater than or equal to
@var{x}.

@subheading Return Value

The smallest integer value greater than or equal to @var{x}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node cfgetispeed, cfgetospeed, ceil, Alphabetical List
@unnumberedsec cfgetispeed
@c From file ./posix/termios/cfgtispd.txh
@findex cfgetispeed
@subheading Syntax

@example
#include <termios.h>

speed_t cfgetispeed (const struct termios *termiosp);
@end example

@subheading Description

This function gets the input line speed stored in the structure
@var{termiosp}.  @xref{Termios functions}, for more details about this
structure and the baudrate values it supports.

Note that the termios emulation handles console only, and that the input
baudrate value is ignored by this implementation.

@subheading Return Value

The input line speed on success, (speed_t) -1 for error.



@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node cfgetospeed, cfmakeraw, cfgetispeed, Alphabetical List
@unnumberedsec cfgetospeed
@c From file ./posix/termios/cfgtospd.txh
@findex cfgetospeed
@subheading Syntax

@example
#include <termios.h>

speed_t cfgetospeed (const struct termios *termiosp);
@end example

@subheading Description

This function gets the output line speed stored in the structure
@var{termiosp}.  @xref{Termios functions}, for more details about this
structure and the baudrate values it supports.

Note that the termios emulation handles console only, and that the
baudrate value has no effect in this implementation.

@subheading Return Value

The output line speed on success, (speed_t) -1 for error.



@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node cfmakeraw, cfree, cfgetospeed, Alphabetical List
@unnumberedsec cfmakeraw
@c From file ./compat/termios/cfmakraw.txh
@findex cfmakeraw
@subheading Syntax

@example
#include <termios.h>

void cfmakeraw (struct termios *termiosp);
@end example

@subheading Description

This function sets the structure specified by @var{termiosp} for raw
mode.  It is provided for compatibility only.  Note that the termios
emulation handles console only.

@subheading Return Value

Zero on success, nonzero on failure.



@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node cfree, cfsetispeed, cfmakeraw, Alphabetical List
@unnumberedsec cfree
@c From file ./compat/stdlib/cfree.txh
@findex cfree
@subheading Syntax

@example
#include <stdlib.h>

void cfree(void *pointer);
@end example

@subheading Description

This function returns the memory allocated by calloc (@pxref{calloc}) to
the heap. 

@subheading Return Value
  
None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
Complex *x = calloc(12, sizeof(Complex));
cfree(x);
@end example

@c -----------------------------------------------------------------------------
@node cfsetispeed, cfsetospeed, cfree, Alphabetical List
@unnumberedsec cfsetispeed
@c From file ./posix/termios/cfstispd.txh
@findex cfsetispeed
@subheading Syntax

@example
#include <termios.h>

int cfsetispeed (struct termios *termiosp, speed_t speed);
@end example

@subheading Description

This function sets the input line speed stored in the structure
@var{termiosp} to @var{speed}.  @xref{Termios functions}, for more
details about this structure and the baudrate values it supports.

Note that the termios emulation handles console only, and that the
baudrate values have no effect in this implementation.

@subheading Return Value

Zero on success, nonzero on failure.



@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node cfsetospeed, cfsetspeed, cfsetispeed, Alphabetical List
@unnumberedsec cfsetospeed
@c From file ./posix/termios/cfstospd.txh
@findex cfsetospeed
@subheading Syntax

@example
#include <termios.h>

int cfsetospeed (struct termios *termiosp, speed_t speed);
@end example

@subheading Description

This function sets the output line speed stored in the structure
@var{termiosp} to @var{speed}.  @xref{Termios functions}, for more
details about this structure and the baudrate values it supports.

Note that the termios emulation handles console only, and that the
baudrate values have no effect in this implementation.

@subheading Return Value

Zero on success, nonzero on failure.



@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node cfsetspeed, cgets, cfsetospeed, Alphabetical List
@unnumberedsec cfsetspeed
@c From file ./compat/termios/cfstispd.txh
@findex cfsetspeed
@subheading Syntax

@example
#include <termios.h>

int cfsetspeed (struct termios *termiosp, speed_t speed);
@end example

@subheading Description

This function sets the input and output line speed stored in the
structure @var{termiosp} to @var{speed}.  It is provided for
compatibility only.  Note that the termios emulation handles console
only.

@subheading Return Value

Zero on success, nonzero on failure.



@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node cgets, chdir, cfsetspeed, Alphabetical List
@unnumberedsec cgets
@c From file ./pc_hw/co80/conio.txh
@findex cgets
@subheading Syntax

@example
#include <conio.h>

char *cgets(char *_str);
@end example

@subheading Description

Get a string from the console.  This will take advantage of any
command-line editing TSRs.  To use, you must pre-fill the first
character of the buffer.  The first character is the size of the
buffer.  On return, the second character is the number of characters
read.  The third character is the first character read.

@subheading Return Value

A pointer to the first character read.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node chdir, _check_v2_prog, cgets, Alphabetical List
@unnumberedsec chdir
@c From file ./posix/unistd/chdir.txh
@findex chdir
@subheading Syntax

@example
#include <unistd.h>

int chdir(const char *new_directory);
@end example

@subheading Description

This function changes the current directory to @var{new_directory}.
If a drive letter is specified, the current directory for that drive
is changed and the current disk is set to that drive, else the current
directory for the current drive is changed.

@subheading Return Value

Zero if the new directory exists, else nonzero and @code{errno} set if error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
if (chdir("/tmp"))
  perror("/tmp");
@end example

@c -----------------------------------------------------------------------------
@node _check_v2_prog, chmod, chdir, Alphabetical List
@unnumberedsec _check_v2_prog
@c From file ./dos/process/chkv2prg.txh
@findex _check_v2_prog
@tindex _v1_stubinfo@r{ type}
@tindex _v2_prog_type@r{ type}
@subheading Syntax

@example
#include <sys/system.h>

const _v2_prog_type *_check_v2_prog(const char *program, int fd);

@end example

@subheading Description

This function checks a given program for various known types of
executables and/or other things.  This function provides two different
entry points.  One is to call the function with a not @code{NULL}
pointer as @code{program} (in this case @code{fd} is ignored),
then the file named by @code{program} is opened and closed by
@code{_check_v2_prog}.

When you pass @code{NULL} as @code{program}, then you have to pass
a valid file handle in @code{fd} and @code{_check_v2_prog} uses
that handle and does also not close the file on return.

@subheading Return Value
@code{_v2_prog_type} is defined in @file{sys/system.h} like the following:

@example

typedef struct @{
  char magic[16];
  int struct_length;
  char go32[16];
  unsigned char buffer[0];
@} _v1_stubinfo;


typedef struct @{
  union @{
    unsigned version:8; /* The version of DJGPP created that COFF exe */
    struct @{
      unsigned minor:4; /* The minor version of DJGPP */
      unsigned major:4; /* The major version of DJGPP */
    @} v;
  @} version;

  unsigned object_format:4; /* What an object format */
# define _V2_OBJECT_FORMAT_UNKNOWN 0x00
# define _V2_OBJECT_FORMAT_COFF    0x01
# define _V2_OBJECT_FORMAT_PE_COFF 0x02

  unsigned exec_format:4; /* What an executable format */
# define _V2_EXEC_FORMAT_UNKNOWN    0x00
# define _V2_EXEC_FORMAT_COFF       0x01
# define _V2_EXEC_FORMAT_STUBCOFF   0x02
# define _V2_EXEC_FORMAT_EXE        0x03
# define _V2_EXEC_FORMAT_UNIXSCRIPT 0x04

  unsigned valid:1; /* Only when nonzero all the information is valid */

  unsigned has_stubinfo:1; /* When nonzero the stubinfo info is valid */

  unsigned unused:14;

  _v1_stubinfo *stubinfo;
@} _v2_prog_type;

@end example

The macros shown above can be used to test the different members of that
structure for known values.

@strong{Warning:} Do not modify any of the data in this structure.

After calling @code{_check_v2_prog} you should check at first the member
@code{valid}.  Only if this is nonzero you can be sure that all the other
information in the struct is valid.

The same is for the @code{stubinfo} member of the above struct, it is
valid only, when @code{has_stubinfo} is nonzero.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

To use the information returned in the struct you can use code like
the following:

@example

#include <stdio.h>
#include <sys/system.h>

int main()
@{
  const _v2_prog_type *type;
  /* Since we pass a valid name, we can use -1 as the second argument */
  type = _check_v2_prog ("foo", -1);

  /* There was something wrong */
  if (!type->valid)
  @{
    fprintf(stderr, "Could not check the file 'foo'. Giving up.\\n");
    return 1;
  @}

  /* Currently only the COFF format is valid to be a V2 executable */
  if (type->object_format != _V2_OBJECT_FORMAT_COFF)
  @{
    fprintf(stderr, "File 'foo' is not in COFF format\\n");
    return 2;
  @}

  /* The major version is not 2 */
  if (type->version.v.major != 2)
  @{
    fprintf(stderr, "File 'foo' is not from DJGPP 2.xx\\n");
    return 3;
  @}

  fprintf(stdout, "File 'foo' is a valid DJGPP 2.xx executable\\n");

  if (type->exec_format == _V2_EXEC_FORMAT_STUBCOFF)
  @{
    fprintf(stdout, "File 'foo' has a stub loader prepended\\n");
  @}

  return 0;
@}

@end example

@c -----------------------------------------------------------------------------
@node chmod, _chmod, _check_v2_prog, Alphabetical List
@unnumberedsec chmod
@c From file ./posix/sys/stat/chmod.txh
@findex chmod
@subheading Syntax

@example
#include <sys/stat.h>

int chmod(const char *path, mode_t mode);
@end example

@subheading Description

This function changes the mode (writable or write-only) of the specified
file.  The value of @var{mode} can be a combination of one or more of
the following:

@table @code

@item S_IRUSR

Make the file readable for the owner.

@item S_IWUSR

Make the file writable for the owner.

@item S_IRGRP

Make the file readable for the group.

@item S_IWGRP

Make the file writeable for the group.

@item S_IROTH

Make the file readable for the world.

@item S_IWOTH

Make the file writeable for the world.

@end table

Some @code{S_I*} constants are ignored for regular files:

@itemize @bullet
@item
@code{S_I*GRP} and @code{S_I*OTH} are ignored, because DOS/Windows
has no concept of ownership, so all files are considered to belong
to the user;

@item
@code{S_IR*} are ignored, because files are always readable on DOS/Windows.
@end itemize

This function can be hooked by File System Extensions
(@pxref{File System Extensions}).

@subheading Return Value

Zero if the file exists and the mode was changed, else nonzero. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
chmod("/tmp/dj.dat", S_IWUSR|S_IRUSR);
@end example

@c -----------------------------------------------------------------------------
@node _chmod, chown, chmod, Alphabetical List
@unnumberedsec _chmod
@c From file ./dos/io/_chmod.txh
@findex _chmod
@subheading Syntax
 
@example
#include <io.h>
 
int _chmod(const char *filename, int func, mode_t mode);
@end example
 
@subheading Description
 
This is a direct connection to the MS-DOS chmod function call, int
0x21, %ax = 0x4300/0x4301.  If @var{func} is 0, then DOS is called with
AX = 0x4300, which returns an attribute byte of a file.  If @var{func}
is 1, then the attributes of a file are set as specified in @var{mode}.
Note that the directory and volume attribute bits must always be 0 when
@code{_chmod()} is called with @var{func = 1}, or else the call will fail.
The third argument is optional when getting attributes.
The attribute bits are defined as follows:
 
@example
  Bit       Meaning
76543210
.......1    Read-only
......1.    Hidden
.....1..    System
....1...    Volume Label
...1....    Directory
..1.....    Archive
xx......    Reserved (used by some network redirectors)
@end example

On platforms where the LFN API (@pxref{_use_lfn, LFN}) is available,
@code{_chmod} calls function 0x7143 of Interrupt 21h, to support long
file names.
 
@subheading Return Value
 
If the file exists, @code{_chmod()} returns its attribute byte in case
it succeeded, or -1 in case of failure.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node chown, chsize, _chmod, Alphabetical List
@unnumberedsec chown
@c From file ./posix/unistd/chown.txh
@findex chown
@subheading Syntax

@example
#include <unistd.h>

int chown(const char *file, int owner, int group);
@end example

@subheading Description

This function changes the ownership of the open file specified by @var{file}
to the user ID @var{owner} and group ID @var{group}.

This function does nothing under MS-DOS.  This function can 
be hooked by File System Extensions (@pxref{File System Extensions}).

@subheading Return Value

This function always returns zero if the file exists, else it returns
-1 and sets @code{errno} to @code{ENOENT}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable

@c -----------------------------------------------------------------------------
@node chsize, cleanup_client, chown, Alphabetical List
@unnumberedsec chsize
@c From file ./compat/io/chsize.txh
@findex chsize
@subheading Syntax

@example
#include <io.h>

int chsize(int handle, long size);
@end example

@subheading Description

Just calls ftruncate (@pxref{ftruncate}).

@subheading Return Value

Zero on success, -1 on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node cleanup_client, _clear87, chsize, Alphabetical List
@unnumberedsec cleanup_client
@c From file ./debug.txh
@findex cleanup_client

@subheading Syntax

@example
#include <debug/dbgcom.h>

void cleanup_client (void);
@end example

@subheading Description

This function is typically called when the debugged process exits or is
aborted.  It restores segment descriptors, closes file handles that were
left open by the debuggee, frees protected-mode and conventional memory
and any segment descriptors allocated by the debuggee, and restores the
debugger's original signal handlers.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _clear87, __clear_fd_flags, cleanup_client, Alphabetical List
@unnumberedsec _clear87
@c From file ./pc_hw/fpu/clear87.txh
@findex _clear87
@subheading Syntax

@example
#include <float.h>

unsigned int _clear87(void);
@end example

@subheading Description

Clears the floating point processor's exception flags.

@subheading Return Value

The previous status word.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __clear_fd_flags, __clear_fd_properties, _clear87, Alphabetical List
@unnumberedsec __clear_fd_flags
@c From file ./dos/io/fd_props.txh
@findex __clear_fd_flags
@subheading Syntax

@example
#include <libc/fd_props.h>

void __clear_fd_flags(int fd, unsigned long flags);
@end example

@subheading Description

This internal function clears the combination of flags @var{flags} from
the flags associated with the file descriptor @var{fd}.  The flags are
some properties that may be associated with a file descriptor
(@pxref{__set_fd_properties}).

The caller should first check that @var{fd} has properties associated
with it, by calling @code{__has_fd_properties}
(@pxref{__has_fd_properties}).

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __clear_fd_properties, clearerr, __clear_fd_flags, Alphabetical List
@unnumberedsec __clear_fd_properties
@c From file ./dos/io/fd_props.txh
@findex __clear_fd_properties
@subheading Syntax

@example
#include <libc/fd_props.h>

int __clear_fd_properties(int fd);

@end example

@subheading Description

This internal function is called when the file descriptor @var{fd} is
no longer valid.  The usage count of the associated @code{fd_properties} struct
is decremented.  And if it becomes zero, this function performs cleanup
and releases the memory used by the @code{fd_properties} struct.

For more information, see @code{__set_fd_properties}
(@pxref{__set_fd_properties}) and @code{__dup_fd_properties}
(@pxref{__dup_fd_properties}).

@subheading Return Value

Always returns 0 for success.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node clearerr, clock, __clear_fd_properties, Alphabetical List
@unnumberedsec clearerr
@c From file ./ansi/stdio/clearerr.txh
@findex clearerr
@subheading Syntax

@example
#include <stdio.h>

void clearerr(FILE *stream);
@end example

@subheading Description

This function clears the EOF and error indicators for the file
@var{stream}. 

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
clearerr(stdout);
@end example

@c -----------------------------------------------------------------------------
@node clock, close, clearerr, Alphabetical List
@unnumberedsec clock
@c From file ./pc_hw/timer/clock.txh
@findex clock
@subheading Syntax

@example
#include <time.h>

clock_t clock(void);
@end example

@subheading Description

This function returns the number of clock ticks since an arbitrary time,
actually, since the first call to @code{clock}, which itself returns
zero.  The number of tics per second is CLOCKS_PER_SEC.

@subheading Return Value

The number of tics.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
printf("%d seconds have elapsed\n", clock()/CLOCKS_PER_SEC);
@end example

@c -----------------------------------------------------------------------------
@node close, _close, clock, Alphabetical List
@unnumberedsec close
@c From file ./posix/unistd/close.txh
@findex close
@subheading Syntax

@example
#include <unistd.h>

int close(int fd);
@end example

@subheading Description

The open file associated with @var{fd} is closed.

@subheading Return Value

Zero if the file was closed, nonzero if @var{fd} was invalid or already closed.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
int fd = open("data", O_RDONLY);
close(fd);
@end example

@c -----------------------------------------------------------------------------
@node _close, closedir, close, Alphabetical List
@unnumberedsec _close
@c From file ./dos/io/_close.txh
@findex _close
@subheading Syntax

@example
#include <io.h>

int _close(int fd);
@end example

@subheading Description

This is a direct connection to the MS-DOS close function call, int
0x21, %ah = 0x3e. This function can be hooked by the
@xref{File System Extensions}. If you don't want this, you should
use @xref{_dos_close}.

@subheading Return Value

Zero if the file was closed, else nonzero. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node closedir, clreol, _close, Alphabetical List
@unnumberedsec closedir
@c From file ./posix/dirent/closedir.txh
@findex closedir
@subheading Syntax

@example
#include <dirent.h>

int closedir(DIR *dir);
@end example

@subheading Description

This function closes a directory opened by opendir (@pxref{opendir}).

@subheading Return Value

Zero on success, nonzero if @var{dir} is invalid.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node clreol, clrscr, closedir, Alphabetical List
@unnumberedsec clreol
@c From file ./pc_hw/co80/conio.txh
@findex clreol
@subheading Syntax

@example
#include <conio.h>

void clreol(void);
@end example

@subheading Description

Clear to end of line.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node clrscr, confstr, clreol, Alphabetical List
@unnumberedsec clrscr
@c From file ./pc_hw/co80/conio.txh
@findex clrscr
@subheading Syntax

@example
#include <conio.h>

void clrscr(void);
@end example

@subheading Description

Clear the entire screen.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node confstr, _conio_gettext, clrscr, Alphabetical List
@unnumberedsec confstr
@c From file ./posix/unistd/confstr.txh
@findex confstr
@subheading Syntax

@example
#include <unistd.h>

size_t confstr(int name, char *buf, size_t len);
@end example

@subheading Description

This function stores various system-dependent configuration values
in @var{buf}.  @var{name} is one of the following:

@table @code

@item _CS_PATH

Returns a path to the standard POSIX utilities.

@item _CS_POSIX_V6_ILP32_OFF32_CFLAGS

Returns the compile-time flags required to build an application using 32-bit
@code{int}, @code{long}, pointer, and @code{off_t} types.

@item _CS_POSIX_V6_ILP32_OFF32_LDFLAGS

Returns the link-time flags required to build an application using 32-bit
@code{int}, @code{long}, pointer, and @code{off_t} types.

@item _CS_POSIX_V6_ILP32_OFF32_LIBS

Returns the set of libraries required to build an application using 32-bit
@code{int}, @code{long}, pointer, and @code{off_t} types.

@end table

If @var{len} is not zero and @var{name} has a defined value, that value
is copied into @var{buf} and null terminated.  If the length of the string
to be copied plus the null terminator is greater than @var{len} bytes,
the string is truncated to @math{@var{len}-1} bytes and the result is
null terminated.

If @var{len} is zero, nothing is copied into @var{buf} and the size of the
buffer required to store the string is returned.

@subheading Return Value

If @var{name} has a defined value, the minimum size of the buffer required
to hold the string including the terminating null is returned.  If this value
is greater than @var{len}, then @var{buf} is truncated.

If @var{name} is valid but does not have a defined value, zero is returned.

If @var{name} is invalid, zero is returned and @code{errno} is set to
@code{EINVAL}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
char *path;
size_t path_len;

path_len = confstr (_CS_PATH, NULL, 0);
path = malloc(path_len);
confstr(_CS_PATH, path, path_len);
@end example

@c -----------------------------------------------------------------------------
@node _conio_gettext, _conio_kbhit, confstr, Alphabetical List
@unnumberedsec _conio_gettext
@c From file ./pc_hw/co80/conio.txh
@findex _conio_gettext
@subheading Syntax

@example
#include <conio.h>

int     _conio_gettext(int _left, int _top, int _right, int _bottom, void *_destin);
@end example

@subheading Description

Retrieve a block of screen characters into a buffer.

@subheading Return Value

1

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _conio_kbhit, _control87, _conio_gettext, Alphabetical List
@unnumberedsec _conio_kbhit
@c From file ./pc_hw/co80/conio.txh
@findex _conio_kbhit
@subheading Syntax

@example
#include <conio.h>

int _conio_kbhit(void);
@end example

@subheading Description

Determines whether or not a character is waiting at the keyboard.  If
there is an ungetch'd character, this function returns true.  Note
that if you include @code{conio.h}, the @code{kbhit} (@pxref{kbhit})
function is redefined to be this function instead.

@subheading Return Value

Nonzero if a key is waiting, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node _control87, cos, _conio_kbhit, Alphabetical List
@unnumberedsec _control87
@c From file ./pc_hw/fpu/cntrl87.txh
@findex _control87
@subheading Syntax

@example
#include <float.h>

unsigned int _control87(unsigned int newcw, unsigned int mask);
@end example

@subheading Description

This function sets and retrieves the FPU's @dfn{control word}.

The control word is a special 16-bit register maintained by the math
coprocessor.  By setting and clearing bit fields in the control word,
you can exercise control of certain aspects of coprocessor operation.
The individual bits of the x87 control word are defined by macros in
float.h, and shown in this table:

@example
---- ---- --XX XXXX = MCW_EM - exception masks (1=handle exception
                                                internally, 0=fault)
---- ---- ---- ---X = EM_INVALID - invalid operation
---- ---- ---- --X- = EM_DENORMAL - denormal operand
---- ---- ---- -X-- = EM_ZERODIVIDE - divide by zero
---- ---- ---- X--- = EM_OVERFLOW - overflow
---- ---- ---X ---- = EM_UNDERFLOW - underflow
---- ---- --X- ---- = EM_INEXACT - rounding was required
---- --XX ---- ---- = MCW_PC - precision control
---- --00 ---- ---- = PC_24 - single precision
---- --10 ---- ---- = PC_53 - double precision
---- --11 ---- ---- = PC_64 - extended precision
---- XX-- ---- ---- = MCW_RC - rounding control
---- 00-- ---- ---- = RC_NEAR - round to nearest
---- 01-- ---- ---- = RC_DOWN - round towards -Inf
---- 10-- ---- ---- = RC_UP - round towards +Inf
---- 11-- ---- ---- = RC_CHOP - round towards zero
---X ---- ---- ---- = MCW_IC - infinity control (obsolete,
                                                 always affine)
---0 ---- ---- ---- = IC_AFFINE - -Inf < +Inf
---1 ---- ---- ---- = IC_PROJECTIVE - -Inf == +Inf
@end example

@code{_control87} uses the value of @var{newcw} and @var{mask} variables
together to determine which bits of the FPU's control word should be
set, and to what values.  For each bit in @var{mask} that is set (equals
to 1), the corresponding bit in @var{newcw} specifies the new value of
the same bit in the FPU's control word, which @code{_control87} should
set.  Bits which correspond to reset (zero) bits in @var{mask} are not
changed in the FPU's control word.  Thus, using a zero value for
@var{mask} retrieves the current value of the control word without
changing it.

The exception bits @code{MCW_EM} (the low-order 6 bits) of the control
word define the exception @emph{mask}.  That is, if a certain bit is
set, the corresponding exception will be masked, i.e., it will not
generate an FP exception (which normally causes signal @code{SIGFPE} to
be delivered).  A masked exception will be handled internally by the
coprocessor.  In general, that means that it will generate special
results, such as @dfn{NaN}, Not-a-Number (e.g., when you attempt to
compute a square root of a negative number), denormalized result (in
case of underflow), or infinity (e.g., in the case of division by zero,
or when the result overflows).

By default, DJGPP startup code masks all FP exceptions.

The precision-control field @code{MCW_PC} (bits 8 and 9) controls the
internal precision of the coprocessor by selecting the number of
precision bits in the mantissa of the FP numbers.  The values
@code{PC_24}, @code{PC_53}, and @code{PC_64} set the precision to 24,
53, and 64-bit mantissa, respectively.  This feature of the coprocessor
is for compatibility with the @dfn{IEEE 745 standard} and only affect
the @code{FADD}, @code{FSUB} @code{FSUBR}, @code{FMUL}, @code{FDIV},
@code{FDIVR}, and @code{FSQRT} instructions.  Lowering the precision
will @strong{not} decrease the execution time of FP instructions.

The @code{MCW_PC} field is set to use the full-precision 64-bit
mantissa by the DJGPP startup code.

The rounding-control field @code{MCW_RC} (bits 10 and 11) controls the
type (round or chop) and direction (-Inf or +Inf) of the rounding.  It
only affects arithmetic instructions.  Set to round-to-nearest state by
the DJGPP startup code.

The infinity-control bit @code{MCW_IC} has no effect on 80387 and later
coprocessors.

@subheading Return Value

The previous control word.

(Note that this is different from what @code{_control87} from the
Borland C library which returns the @emph{new} control word.)

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  /* mask all exceptions, except invalid operation */
  _control87 (0x033e, 0xffff);
@end example

@c -----------------------------------------------------------------------------
@node cos, cosh, _control87, Alphabetical List
@unnumberedsec cos
@c From file ./ansi/math/cos.txh
@findex cos
@subheading Syntax

@example
#include <math.h>

double cos(double x);
@end example

@subheading Description

This function computes the cosine of @var{x} (which should be given in
radians).

@subheading Return Value

The cosine of @var{x}.  If the absolute value of @var{x} is finite but
greater than or equal to @math{2^63}, the value is 1 (since for
arguments that large each bit of the mantissa is more than @code{Pi}).
If the value of @var{x} is infinite or @code{NaN}, the return value is
@code{NaN} and @code{errno} is set to @code{EDOM}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Accuracy

In general, this function's relative accuracy is about
@math{1.7*10^(-16)}, which is close to the machine precision for a
@code{double}.  However, for arguments very close to @code{Pi/2} and its
odd multiples, the relative accuracy can be many times worse, due to
loss of precision in the internal FPU computations.  Since
@math{cos(Pi/2)} is zero, the absolute accuracy is still very good; but
if your program needs to preserve high @emph{relative} accuracy for such
arguments, link with @samp{-lm} and use the version of @code{cos} from
@file{libm.a} which does elaborate argument reduction, but is about
three times slower.
@c -----------------------------------------------------------------------------
@node cosh, cprintf, cos, Alphabetical List
@unnumberedsec cosh
@c From file ./ansi/math/cosh.txh
@findex cosh
@subheading Syntax

@example
#include <math.h>

double cosh(double x);
@end example

@subheading Description

This function computes the hyperbolic cosine of @var{x}.

@subheading Return Value

The hyperbolic cosine of @var{x}.  If the value of @var{x} is a
@code{NaN}, the return value is @code{NaN} and @code{errno} is set to
@code{EDOM}.  If the value of @var{x} is so large that the result would
overflow a @code{double}, the return value is @code{Inf} and
@code{errno} is set to @code{ERANGE}.  If @var{x} is either a positive
or a negative infinity, the result is @code{+Inf}, and @code{errno} is
not changed.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node cprintf, cputs, cosh, Alphabetical List
@unnumberedsec cprintf
@c From file ./pc_hw/co80/conio.txh
@findex cprintf
@subheading Syntax

@example
#include <conio.h>

int cprintf(const char *_format, ...);
@end example

@subheading Description

Like @code{printf} (@pxref{printf}), but prints through the console,
taking into consideration window borders and text attributes.  There
is currently a 2048-byte limit on the size of each individual cprintf
call.

@subheading Return Value

The number of characters written.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node cputs, creat, cprintf, Alphabetical List
@unnumberedsec cputs
@c From file ./pc_hw/co80/conio.txh
@findex cputs
@subheading Syntax

@example
#include <conio.h>

int cputs(const char *_str);
@end example

@subheading Description

Puts the string onto the console.  The cursor position is updated.

@subheading Return Value

Zero on success.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node creat, _creat, cputs, Alphabetical List
@unnumberedsec creat
@c From file ./posix/fcntl/creat.txh
@findex creat
@subheading Syntax

@example
#include <fcntl.h>
#include <sys/stat.h> /* for mode definitions */

int creat(const char *filename, mode_t mode);
@end example

@subheading Description

This function creates the given file and opens it for writing.  If the
file exists, it is truncated to zero size, unless it is read-only, in
which case the function fails.  If the file does not exist, it will be
created read-only if @var{mode} does not have @code{S_IWUSR} set. 

@subheading Return Value

A file descriptor >= 0, or a negative number on error. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
int fd = creat("data", S_IRUSR|S_IWUSR);
write(fd, buf, 1024);
close(fd);
@end example

@c -----------------------------------------------------------------------------
@node _creat, _creatnew, creat, Alphabetical List
@unnumberedsec _creat
@c From file ./dos/io/_creat.txh
@findex _creat
@subheading Syntax

@example
#include <io.h>

int _creat(const char *path, int attrib);
@end example

@subheading Description

This is a direct connection to the MS-DOS creat function call, int 0x21,
%ah = 0x3c, on versions of DOS earlier than 7.0. On DOS version
7.0 or later @code{_creat} calls function int 0x21, %ax = 0x6c00

On platforms where the LFN API (@pxref{_use_lfn, LFN}) is available,
@code{_creat} calls function 0x716C of Interrupt 21h, to support long
file names.

On FAT32 file systems file sizes up to 2^32-2 are supported. Note
that WINDOWS 98 has a bug which only lets you create these big files
if LFN is enabled. In plain DOS mode it plainly works.

The file is set to binary mode.  

This function can be hooked by File System Extensions
(@pxref{File System Extensions}).  If you don't want this, you should use
@code{_dos_creat} (@pxref{_dos_creat}) or @code{_dos_creatnew}
(@pxref{_dos_creatnew}).

@subheading Return Value

The new file descriptor, else -1 on error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _creatnew, crlf2nl, _creat, Alphabetical List
@unnumberedsec _creatnew
@c From file ./dos/io/_creat_n.txh
@findex _creatnew
@subheading Syntax

@example
#include <fcntl.h>
#include <dir.h>
#include <io.h>

int _creatnew(const char *path, int attrib, int flags);
@end example

@subheading Description

This function creates a file given by @var{path} and opens it, like
@code{_creat} does, but only if it didn't already exist.  If the named
file exists, @code{_creatnew} fails.  (In contrast, @code{_creat} opens
existing files and overwrites their contents, see @ref{_creat}.)

The attributes of the created file are determined by @var{attrib}.  The
file is usually given the normal attribute (00H).  If @var{attrib} is
non-zero, additional attributes will be set.  The following macros,
defined on @code{<dir.h>}, can be used to control the attributes of the
created file (the associated numeric values appear in parentheses):

@table @code
@item FA_RDONLY (1)
The file is created with the read-only bit set.

@item FA_HIDDEN (2)
The file is created with the hidden bit set.  Such files will not appear
in directory listings unless you use special options to the commands
which list files.

@item FA_SYSTEM (4)
The file is created with the system bit set.  Such files will not appear
in directory listings unless you use special options to the commands
which list files.
@end table

Other bits (@code{FA_LABEL} and @code{FA_DIREC}) are ignored by DOS.

The argument @var{flags} controls the sharing mode and the fine details
of how the file is handled by the operating system.  The following
macros, defined on @code{<fcntl.h>}, can be used for this (associated
numeric values are given in parentheses):

@table @code
@item SH_COMPAT (00h)
Opens the file in compatibility mode, which allows any other process to
open the file and read from the file any number of times.

@item SH_DENYRW (10h)
Denies both read and write access by other processes.

@item SH_DENYWR (20h)
Denies write access by other processes.

@item SH_DENYRD (30h)
Denies read access by other processes.

@item SH_DENYNO (40h)
Allows read and write access by other processes, but prevents other
processes from opening the file in compatibility mode.
@end table

Note that the file is always open for both reading and writing;
@code{_creatnew} ignores any bits in the lower nibble of @var{flags}
(@code{O_RDONLY}, @code{O_WRONLY}, etc.).

@code{_creatnew} calls DOS function 716Ch when long file names are
supported, 6C00h otherwise.  (On DOS version 3.x, function 5B00h is
called which ignores the value of @var{flags}, since function 6C00h is
only supported by DOS 4.0 and later.)

The file handle returned by @code{_creatnew} is set to binary mode. 

This function can be hooked by the Filesystem Extensions handlers, as
described in @ref{File System Extensions}.  If you don't want this, you
should use @code{_dos_creatnew} (@pxref{_dos_creatnew}) instead.

@subheading Return Value

The new file descriptor, else -1 on error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node crlf2nl, __crt0_glob_function, _creatnew, Alphabetical List
@unnumberedsec crlf2nl
@c From file ./dos/io/crlf2nl.txh
@findex crlf2nl
@subheading Syntax

@example
#include <io.h>

size_t crlf2nl(char *buf, ssize_t len);
@end example

@subheading Description

This function removes Ctrl-M characters from the given @var{buf}. 

@subheading Return Value

The number of characters remaining in the buffer are returned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __crt0_glob_function, __crt0_load_environment_file, crlf2nl, Alphabetical List
@unnumberedsec __crt0_glob_function
@c From file ./crt0/crt1.txh
@findex __crt0_glob_function
@subheading Syntax

@example
#include <crt0.h>

char **__crt0_glob_function(char *_argument);
@end example

@subheading Description

If the application wishes to provide a wildcard expansion function, it
should define a @code{__crt0_glob_function} function.  It should return
a list of the expanded values, or 0 if no expansion will occur.  The
startup code will free the returned pointer if it is nonzero.

If no expander function is provided, wildcards will be expanded in the
POSIX.1 style by the default @code{__crt0_glob_function} from the C
library.  To disable expansion, provide a @code{__crt0_glob_function}
that always returns 0.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __crt0_load_environment_file, __crt0_setup_arguments, __crt0_glob_function, Alphabetical List
@unnumberedsec __crt0_load_environment_file
@c From file ./crt0/crt1.txh
@findex __crt0_load_environment_file
@vindex DJGPP@r{ environment variable}
@subheading Syntax

@example
#include <crt0.h>

void   __crt0_load_environment_file(char *_app_name);
@end example

@subheading Description

This function, provided by libc.a, does all the work required to load
additional environment variables from the file @file{djgpp.env} whose
full pathname is given by the @code{DJGPP} environment variable.  If the
application does not use environment variables, the programmer can
reduce the size of the program image by providing a version of this
function that does nothing.

@xref{__crt0_setup_arguments}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __crt0_setup_arguments, _crt0_startup_flags, __crt0_load_environment_file, Alphabetical List
@unnumberedsec __crt0_setup_arguments
@c From file ./crt0/crt1.txh
@findex __crt0_setup_arguments
@subheading Syntax

@example
#include <crt0.h>

void   __crt0_setup_arguments(void);
@end example

@subheading Description

This function, provided by libc.a, does all the work required to
provide the two arguments passed to main() (usually @code{argc} and
@code{argv}).  If main() does not use these arguments, the programmer
can reduce the size of the program image by providing a version of
this function that does nothing.

Note that since the default @code{__crt0_setup_arguments_function} will
@emph{not} expand wildcards inside quotes (@kbd{"} or @kbd{'}), you
can quote a part of the argument that doesn't include wildcards and
still have them expanded.  This is so you could use wildcard expansion
with filenames which have embedded whitespace (on LFN filesystems).

@xref{__crt0_load_environment_file}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _crt0_startup_flags, cscanf, __crt0_setup_arguments, Alphabetical List
@unnumberedsec _crt0_startup_flags
@c From file ./crt0/crt1.txh
@vindex _crt0_startup_flags
@vindex LFN@r{ environment variable, how to disable at start-up}
@vindex FNCASE@r{ environment variable, how to disable at start-up}
@subheading Syntax

@example
#include <crt0.h>

int _crt0_startup_flags = ...;
@end example

@subheading Description

This variable can be used to determine what the startup code will (or
will not) do when the program begins.  This can be used to tailor the
startup environment to a particular program.

@table @code

@item _CRT0_FLAG_PRESERVE_UPPER_CASE

If set, @code{argv[0]} is left in whatever case it was.  If not set, all
characters are mapped to lower case.  Note that if the @code{argv0}
field in the @dfn{stubinfo} structure is present, the case of that part
of @code{argv[0]} is not affected. 

@item _CRT0_FLAG_USE_DOS_SLASHES

If set, reverse slashes (dos-style) are preserved in @code{argv[0]}.  If
not set, all reverse slashes are replaced with unix-style slashes.

@item _CRT0_FLAG_DROP_EXE_SUFFIX

If set, the @file{.exe} suffix is removed from the file name component
of @code{argv[0]}.  If not set, the suffix remains. 

@item _CRT0_FLAG_DROP_DRIVE_SPECIFIER

If set, the drive specifier (e.g. @file{C:}) is removed from the
beginning of @code{argv[0]} (if present).  If not set, the drive
specifier remains.

@item _CRT0_FLAG_DISALLOW_RESPONSE_FILES

If set, response files (e.g. @file{@@gcc.rf}) are not expanded.  If not
set, the contents of the response files are used to create arguments.
Note that if the file does not exist, that argument remains unexpanded. 

@item _CRT0_FLAG_KEEP_QUOTES

If set, the quote characters @samp{'}, @samp{"}, and @samp{\} will be
retained in @code{argv[]} elements when processing command lines passed
by DOS and via @code{system}.  This is used by the @code{redir} program,
and should only be needed if you want to get the original command line
exactly as it was passed by the caller.

@item _CRT0_FLAG_FILL_SBRK_MEMORY

If set, fill @code{sbrk}'d memory with a constant value.  If not, memory
gets whatever happens to have been in there, which breaks some
applications.

@item _CRT0_FLAG_FILL_DEADBEEF

If set, fill memory (above) with @code{0xdeadbeef}, else fill with zero.
This is especially useful for debugging uninitialized memory problems.

@item _CRT0_FLAG_NEARPTR

If set, set DS limit to 4GB which allows use of near pointers to DOS
(and other) memory.  WARNING, disables memory protection and bad
pointers may crash the machine or wipe out your data.  This flag is
silently ignored on NT and DOSEmu, which disallow such huge selector
limits.

@item _CRT0_FLAG_NULLOK

If set, disable @sc{null} pointer protection (if it can be controlled at
all).

@item _CRT0_FLAG_NMI_SIGNAL

If set, enabled capture of NMI in exception code.  This may cause problems
with laptops and "green" boxes which use it to wake up.  Default is to 
leave NMIs alone and pass through to real mode code.  You decide.

@item _CRT0_FLAG_NO_LFN

If set, disable usage of long file name functions even on systems (such
as Windows 9X) which support them.  This might be needed to work around
program assumptions on file name format on programs written specifically
for DOS.  Note that this flag overrides the value of the environment
variable @code{LFN}.

@item _CRT0_FLAG_NONMOVE_SBRK

If set, the @code{sbrk} algorithm uses multiple DPMI memory blocks which
makes sure the base of CS/DS/SS does not change.  This may cause
problems with @code{sbrk(0)} values and programs with other assumptions
about @code{sbrk} behavior.  This flag is useful with near pointers,
since a constant pointer to DOS/Video memory can be computed without
needing to reload it after any routine which might call @code{sbrk}.

@item _CRT0_FLAG_UNIX_SBRK

If set, the @code{sbrk} algorithm resizes memory blocks so that the
layout of memory is set up to be the most compatible with Unix
@code{sbrk} expectations.  This mode should not be used with hardware
interrupts, near pointers, and may cause problems with QDPMI virtual
memory.

If your program requires a specific @code{sbrk} behavior, you
should set either this or the previous flag, since the default may
change in different libc releases.

@item _CRT0_DISABLE_SBRK_ADDRESS_WRAP

If set, non-move @code{sbrk} should discard (ignore) memory blocks which are
returned by DPMI which would require address wrap to access (at addresses
below the CS/DS base address).  This bit is automatically set on Windows NT
systems which require it.  It may be manually set on other systems which 
don't require it to retain a more normal memory space layout and better
memory protection.  This bit can be set but should never be cleared.

@item _CRT0_FLAG_LOCK_MEMORY

If set, locks all memory as it is allocated.  This effectively disables
virtual memory, and may be useful if using extensive hardware interrupt
codes in a relatively small image size.  The memory is locked after it
is @code{sbrk}'ed, so the locking may fail.  This bit may be set or cleared
during execution.  When @code{sbrk} uses multiple memory zones, it can be
difficult to lock all memory since the memory block size and location is
impossible to determine.

@item _CRT0_FLAG_PRESERVE_FILENAME_CASE

If set, disables all filename letter-case conversions in functions that
traverse directories (except findfirst/findnext which always return the
filenames exactly as found in the directory entry).  When reset, all
filenames on 8+3 MSDOS filesystems and DOS-style 8+3 filenames on LFN
systems are converted to lower-case by functions such as `readdir',
@code{getcwd}, @code{_fixpath} and others.  Note that when this flag is
set, ALL filenames on MSDOS systems will appear in upper-case, which is
both ugly and will break many Unix-born programs.  Use only if you know
exactly what you are doing!

This flag overrides the value of the environment variable @samp{FNCASE},
@xref{_preserve_fncase}.

@end table

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node cscanf, ctermid, _crt0_startup_flags, Alphabetical List
@unnumberedsec cscanf
@c From file ./pc_hw/co80/conio.txh
@findex cscanf
@subheading Syntax

@example
#include <conio.h>

int cscanf(const char *_format, ...);
@end example

@subheading Description

Like @code{scanf} (@pxref{scanf}), but it reads from the standard input
device directly, avoiding buffering both by DOS and by the library.
Each character is read by @code{getche} (@pxref{getche}).

@subheading Return Value

The number of fields stored.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node ctermid, ctime, cscanf, Alphabetical List
@unnumberedsec ctermid
@c From file ./posix/unistd/ctermid.txh
@findex ctermid
@subheading Syntax

@example
#include <unistd.h>

char *ctermid(char *s);
@end example

@subheading Description

This function returns the name of the current terminal device. Under MS-DOS,
this is always "con".

@subheading Return Value

If @var{s} is null, returns pointer to internal static string "con".
Otherwise, copies "con" to buffer pointed by @var{s}.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node ctime, ctime_r, ctermid, Alphabetical List
@unnumberedsec ctime
@c From file ./ansi/time/ctime.txh
@findex ctime
@subheading Syntax

@example
#include <time.h>

char *ctime(const time_t *cal);
@end example

@subheading Description

This function returns a string representing the time from @var{cal}.
The string returned is always 26 characters and has this format:

@example
Sun Jan 01 12:34:56 1993\n\0
@end example

This function is equivalent to @code{asctime(localtime(cal))}.
@xref{asctime}.
@xref{localtime}.
The string pointed to is in a static buffer and will be overwritten with
each call to @code{ctime}.
The string should be copied if it needs to be preserved.
@xref{ctime_r}, for an alternate interface that allows the caller
to provide a buffer to store the string.

@subheading Return Value

A pointer to a static buffer containing the string representing the time.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node ctime_r, delay, ctime, Alphabetical List
@unnumberedsec ctime_r
@c From file ./ansi/time/ctime.txh
@findex ctime_r
@subheading Syntax

@example
#include <time.h>

char *ctime_r(const time_t *cal, char *buf);
@end example

@subheading Description

This function returns a string representing the time from @var{cal}.
The string returned is always 26 characters and has this format:

@example
Sun Jan 01 12:34:56 1993\n\0
@end example

This function is equivalent to @code{asctime_r(localtime_r(cal,&tm), buf)}
where @var{tm} is a variable of type @code{struct tm}.
@xref{asctime_r}.
@xref{localtime_r}.
The buffer @var{buf} passed must be at least 26 bytes long.

@xref{ctime}, for an alternate ISO Standard interface.

@subheading Return Value

A pointer to @var{buf} containing the string representing the time.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node delay, delline, ctime_r, Alphabetical List
@unnumberedsec delay
@c From file ./dos/dos/delay.txh
@findex delay
@subheading Syntax

@example
#include <dos.h>

void delay(unsigned msec);
@end example

@subheading Description

This function causes the program to pause for @var{msec} milliseconds.
It uses the @code{int 15h} delay function to relinquish the CPU to other
programs that might need it.

Some operating systems that emulate DOS, such as OS/2, Windows/NT,
Windows 2000 and Windows XP hang the DOS session when
the @key{Pause} key is pressed during the call to @code{delay}.
Plain DOS and Windows 3.X and 9X are known to not have this bug.
On Windows 2000 and XP to exit the pause press any key.

Some operating systems, such as Windows 2000 and XP which do not support
@code{int 15h}.  @code{int 1ah} is used instead on these operating
systems.  This method has lower accuracy in the delay length.

Windows 2000 and XP delay resolution is 54.9 millisecond.  Under Windows
2000 and XP the delay function uses the Time Of Day Tick which occurs
18.2 times per second.  This limits the accuracy of the delay to around
27 milliseconds on Windows 2000 and XP.  On Windows 2000 and XP
the Programable Interval Timer works and is a source of higher resolution
than delay currently uses.  Unfortunately PIT and Time Of Day tic
does not appear to be coordinated.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
delay(200); /* delay for 1/5 second */
@end example

@c -----------------------------------------------------------------------------
@node delline, _detect_80387, delay, Alphabetical List
@unnumberedsec delline
@c From file ./pc_hw/co80/conio.txh
@findex delline
@subheading Syntax

@example
#include <conio.h>

void    delline(void);
@end example

@subheading Description

The line the cursor is on is deleted; lines below it scroll up.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node _detect_80387, difftime, delline, Alphabetical List
@unnumberedsec _detect_80387
@c From file ./emu387/fpu.txh
@findex _detect_80387
@subheading Syntax

@example
#include <dos.h>

int _detect_80387(void);
@end example

@subheading Description

Detects whether a numeric coprocessor is present.  Note that
floating-point code will work even without a coprocessor, due to the
existence of emulation.

@subheading Return Value

1 if a coprocessor is present, 0 if not.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
if (_detect_80387())
  printf("You have a coprocessor\n");
@end example

@c -----------------------------------------------------------------------------
@node difftime, dirname, _detect_80387, Alphabetical List
@unnumberedsec difftime
@c From file ./ansi/time/difftime.txh
@findex difftime
@subheading Syntax

@example
#include <time.h>

double difftime(time_t t1, time_t t0);
@end example

@subheading Description

This function returns the difference in time, in seconds, from @var{t0}
to @var{t1}. 

@subheading Return Value

The number of seconds.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
time_t t1, t0;
double elapsed;
time(&t0);
do_something();
time(&t1);
elapsed = difftime(t1, t0);
@end example

@c -----------------------------------------------------------------------------
@node dirname, disable, difftime, Alphabetical List
@unnumberedsec dirname
@c From file ./compat/unistd/dirname.txh
@findex dirname
@subheading Syntax

@example
#include <unistd.h>

char * dirname (const char *fname);
@end example

@subheading Description

This function returns the directory part of the argument @var{fname}
copied to a buffer allocated by calling @code{malloc}.  The directory
part is everything up to but not including the rightmost slash (either
forward- or backslash) in @var{fname}.  If @var{fname} includes a drive
letter but no slashes, the function will return @code{@var{x}:.} where
@var{x} is the drive letter.  If @var{fname} includes neither the drive
letter nor any slashes, @code{"."} will be returned.  Trailing slashes
are removed from the result, unless it is a root directory, with or
without a drive letter.

@subheading Return value

The directory part in malloc'ed storage, or a NULL pointer of either
there's not enough free memory, or @var{fname} is a NULL pointer.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
 printf ("The parent of current directory is %s\n", 
         dirname (getcwd (0, PATH_MAX)));
@end example
@c -----------------------------------------------------------------------------
@node disable, div, dirname, Alphabetical List
@unnumberedsec disable
@c From file ./pc_hw/hwint/disable.txh
@findex disable
@subheading Syntax

@example
#include <dos.h>

int disable(void);
@end example

@subheading Description

This function disables interrupts.

@xref{enable}.

@subheading Return Value

Returns nonzero if the interrupts had been enabled before this call,
zero if they were already disabled.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
int ints_were_enabled;

ints_were_enabled = disable();
. . . do some stuff . . .
if (ints_were_enabled)
  enable();
@end example

@c -----------------------------------------------------------------------------
@node div, __djgpp_exception_toggle, disable, Alphabetical List
@unnumberedsec div
@c From file ./ansi/stdlib/div.txh
@findex div
@tindex div_t@r{ type}
@subheading Syntax

@example
#include <stdlib.h>

div_t div(int numerator, int denominator);
@end example

@subheading Description

Returns the quotient and remainder of the division @var{numerator}
divided by @var{denominator}.  The return type is as follows:

@example
typedef struct @{
  int quot;
  int rem;
@} div_t;
@end example

@subheading Return Value

The results of the division are returned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
div_t d = div(42, 3);
printf("42 = %d x 3 + %d\n", d.quot, d.rem);

div(+40, +3) = @{ +13, +1 @}
div(+40, -3) = @{ -13, +1 @}
div(-40, +3) = @{ -13, -1 @}
div(-40, -3) = @{ +13, -1 @}

@end example

@c -----------------------------------------------------------------------------
@node __djgpp_exception_toggle, __djgpp_map_physical_memory, div, Alphabetical List
@unnumberedsec __djgpp_exception_toggle
@c From file ./go32/dpmiexcp.txh
@findex __djgpp_exception_toggle
@subheading Syntax

@example

#include <sys/exceptn.h>

void __djgpp_exception_toggle(void);

@end example


@subheading Description

This function is automatically called when the program exits, to restore
handling of all the exceptions to their normal state.  You may also call
it from your program, around the code fragments where you need to
temporarily restore @strong{all} the exceptions to their default
handling.  One example of such case might be a call to a library
function that spawns a child program, when you don't want to handle
signals generated while the child runs (by default, those signals are
also passed to the parent).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example

  __djgpp_exception_toggle();
  system("myprog");
  __djgpp_exception_toggle();

@end example


@c -----------------------------------------------------------------------------
@node __djgpp_map_physical_memory, __djgpp_memory_handle, __djgpp_exception_toggle, Alphabetical List
@unnumberedsec __djgpp_map_physical_memory
@c From file ./dpmi/helper/mapmem.txh
@findex __djgpp_map_physical_memory
@subheading Syntax

@example
#include <dpmi.h>

int __djgpp_map_physical_memory(void *our_addr, unsigned long num_bytes,
			        unsigned long phys_addr);
@end example

@subheading Description

This function attempts to map a range of physical memory over the
specified addresses.  One common use of this routine is to map device
memory, such as a linear frame buffer, into the address space of the
calling program.  @var{our_addr}, @var{num_bytes}, and @var{phys_addr}
must be page-aligned.  If they are not page-aligned, @code{errno} will
be set to @code{EINVAL} and the routine will fail.

This routine properly handles memory ranges that span multiple DPMI
handles, while @code{__dpmi_map_device_in_memory_block} does not.

Consult DPMI documentation on function 0508H for details on how this
function works.  Note: since 0508H is a DPMI service new with DPMI
1.0, this call will fail on most DPMI 0.9 servers.  For your program
to work on a wide range of systems, you should not assume this call
will succeed.

Even on failure, this routine may affect a subset of the pages specified.

@subheading Return Value

0 on success, -1 on failure.  On failure, @code{errno} will be set to
@code{EINVAL} for illegal input parameters, or @code{EACCES} if the
DPMI server rejected the mapping request.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
if (__djgpp_map_physical_memory (my_page_aligned_memory, 16384,
                                 0x40000000))
  printf ("Failed to map physical addresses!\n");
@end example
@c -----------------------------------------------------------------------------
@node __djgpp_memory_handle, __djgpp_memory_handle_list, __djgpp_map_physical_memory, Alphabetical List
@unnumberedsec __djgpp_memory_handle
@c From file ./crt0/memhandl.txh
@findex __djgpp_memory_handle
@subheading Syntax

@example
#include <crt0.h>

__djgpp_sbrk_handle *__djgpp_memory_handle(unsigned address);
@end example

@subheading Description

This function returns a pointer to a structure containing the memory 
handle and program relative offset associated with the address passed.
It is just a convenient way to process the __djgpp_memory_handle_list.

@subheading Return Value

A pointer to the __djgpp_sbrk_handle associated with a particular address.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __djgpp_memory_handle_list, __djgpp_memory_handle_size, __djgpp_memory_handle, Alphabetical List
@unnumberedsec __djgpp_memory_handle_list
@c From file ./crt0/crt0.txh
@vindex __djgpp_memory_handle_list
@subheading Syntax

@example
#include <crt0.h>

extern __djgpp_sbrk_handle __djgpp_memory_handle_list[256];
@end example

@subheading Description

This array contains a list of memory handles and program relative offsets
allocated by sbrk() in addition to the handle allocated by the stub.  These 
values are normally not needed unless you are doing low-level DPMI page 
protection or memory mapping.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
#include <crt0.h>

  for(i=0; i<256; i++) @{
    int h, a, s;
    h = __djgpp_memory_handle_list[i].handle;
    a = __djgpp_memory_handle_list[i].address;
    s = __djgpp_memory_handle_size[i];    
    if(a == 0 && i != 0) break;
    printf("handle[%d]=0x%x base=0x%x size=0x%x\n",i,h,a,s);
  @}
@end example

@c -----------------------------------------------------------------------------
@node __djgpp_memory_handle_size, __djgpp_nearptr_disable, __djgpp_memory_handle_list, Alphabetical List
@unnumberedsec __djgpp_memory_handle_size
@c From file ./crt0/crt0.txh
@vindex __djgpp_memory_handle_size
@subheading Syntax

@example
#include <crt0.h>

extern unsigned __djgpp_memory_handle_size[256];
@end example

@subheading Description

This array contains a list of the sizes of the memory regions allocated 
by sbrk() in addition to the memory region allocated by the stub.  These 
values are normally not needed unless you are dumping the memory blocks.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
#include <crt0.h>

  for(i=0; i<256; i++) @{
    int h, a, s;
    h = __djgpp_memory_handle_list[i].handle;
    a = __djgpp_memory_handle_list[i].address;
    s = __djgpp_memory_handle_size[i];    
    if(a == 0 && i != 0) break;
    printf("handle[%d]=0x%x base=0x%x size=0x%x\n",i,h,a,s);
  @}
@end example

@c -----------------------------------------------------------------------------
@node __djgpp_nearptr_disable, __djgpp_nearptr_enable, __djgpp_memory_handle_size, Alphabetical List
@unnumberedsec __djgpp_nearptr_disable
@c From file ./pc_hw/nearptr/nearptr.txh
@findex __djgpp_nearptr_disable
@subheading Syntax

@example
#include <sys/nearptr.h>

void __djgpp_nearptr_disable(void);
@end example

@subheading Description

This function disables near pointers, and re-enables protection.
@xref{__djgpp_nearptr_enable}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __djgpp_nearptr_enable, __djgpp_set_ctrl_c, __djgpp_nearptr_disable, Alphabetical List
@unnumberedsec __djgpp_nearptr_enable
@c From file ./pc_hw/nearptr/nearptr.txh
@findex __djgpp_nearptr_enable
@subheading Syntax

@example
#include <sys/nearptr.h>

int __djgpp_nearptr_enable(void);
@end example

@subheading Description

This function enables "near pointers" to be used to access the DOS
memory arena.  Sort of.  When you call this function, it will return
nonzero if it has successfully enabled near pointers.  If so, you must
add the value @code{__djgpp_conventional_base} to the linear address
of the physical memory.  For example:

@example
if (__djgpp_nearptr_enable())
@{
  short *screen = (short *)(__djgpp_conventional_base + 0xb8000);
  for (i=0; i<80*24*2; i++)
    screen[i] = 0x0720;
  __djgpp_nearptr_disable();
@}
@end example

The variable @code{__djgpp_base_address} contains the linear base
address of the application's data segment.  You can subtract this
value from other linear addresses that DPMI functions might return
in order to obtain a near pointer to those linear regions as well.

If using the Unix-like sbrk algorithm, near pointers are only valid 
until the next @code{malloc}, @code{system}, @code{spawn*}, or 
@code{exec*} function call, since the linear base address of the 
application may be changed by these calls.

WARNING: When you enable near pointers, you disable all the protection
that the system is providing.  If you are not careful, your
application may destroy the data in your computer.  USE AT YOUR OWN
RISK!

@subheading Return Value

Returns 0 if near pointers are not available, or nonzero if they are.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __djgpp_set_ctrl_c, __djgpp_set_page_attributes, __djgpp_nearptr_enable, Alphabetical List
@unnumberedsec __djgpp_set_ctrl_c
@c From file ./go32/dpmiexcp.txh
@findex __djgpp_set_ctrl_c
@subheading Syntax

@example
#include <sys/exceptn.h>

int __djgpp_set_ctrl_c(int enable);
@end example

@subheading Description

This function sets and resets the bit which controls whether signals
@code{SIGINT} and @code{SIGQUIT} (@pxref{signal}) will be raised when
you press the INTR or QUIT keys.  By default these generate signals
which, if uncaught by a signal handler, will abort your program.
However, when you call the @code{setmode} library function to switch the
console reads to binary mode, or open the console in binary mode for
reading, this generation of signals is turned off, because some
programs want to get the @samp{^C} and @samp{^\} characters as any other
character and handle them by themselves.

@code{__djgpp_set_ctrl_c} lets you explicitly determine the effect of
INTR and QUIT keys.  When called with a non-zero, positive value of
@var{enable}, it arranges for @code{SIGINT} and @code{SIGQUIT} signals
to be generated when the appropriate key is pressed; if you call it with
a zero in @var{enable}, these keys are treated as normal characters.  If
@var{enable} is negative, @code{__djgpp_set_ctrl_c} returns the current
state of the signal generation, but doesn't change it.

For getting similar effects via the POSIX @code{termios} functions, see
@ref{tcsetattr}.

Note that the effect of @kbd{Ctrl-@key{BREAK}} key is unaffected by this
function; use the @code{_go32_want_ctrl_break} library function to
control it.

Also note that in DJGPP, the effect of the interrupt signal will only be
seen when the program is in protected mode (@xref{signal, Signal Mechanism},
for more details).  Thus, if you press @kbd{Ctrl-C} while your
program calls DOS (e.g., when reading from the console), the
@code{SIGINT} signal handler will only be called after that call
returns.

@subheading Return Value

The state of @code{SIGINT} and @code{SIGQUIT} generation before the
call: 0 if it was disabled, 1 if it was enabled.  If the argument
@var{enable} is negative, the state is not altered.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example

  setmode(fileno(stdin), O_BINARY);
  if (isatty(fileno(stdin)));
    __djgpp_set_ctrl_c(1);

@end example


@c -----------------------------------------------------------------------------
@node __djgpp_set_page_attributes, __djgpp_set_sigint_key, __djgpp_set_ctrl_c, Alphabetical List
@unnumberedsec __djgpp_set_page_attributes
@c From file ./dpmi/helper/setattr.txh
@findex __djgpp_set_page_attributes
@subheading Syntax

@example
#include <dpmi.h>

int __djgpp_set_page_attributes(void *our_addr, unsigned long num_bytes,
			        unsigned short attributes);
@end example

@subheading Description

This function sets the DPMI page attributes for the pages in a range
of memory.  @var{our_addr} and @var{num_bytes} must be page-aligned.
If they are not page-aligned, @code{errno} will be set to @code{EINVAL}
and the routine will fail.

Consult DPMI documentation on function 0507H for the meaning of the
@var{attributes} argument.  Note: since 0507H is a DPMI service new
with DPMI 1.0, this call will fail on most DPMI 0.9 servers.  For your
program to work on a wide range of systems, you should not assume this
call will succeed.

Even on failure, this routine may affect a subset of the pages specified.

@subheading Return Value

0 on success, -1 on failure.  On failure, @code{errno} will be set to
@code{EINVAL} for illegal input parameters, or @code{EACCES} if the
DPMI server rejected the attribute setting.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
if (__djgpp_set_page_attributes (my_page_aligned_memory, 16384, 0))
  printf ("Failed to make pages uncommitted!\n");
@end example
@c -----------------------------------------------------------------------------
@node __djgpp_set_sigint_key, __djgpp_set_sigquit_key, __djgpp_set_page_attributes, Alphabetical List
@unnumberedsec __djgpp_set_sigint_key
@c From file ./go32/dpmiexcp.txh
@findex __djgpp_set_sigint_key
@subheading Syntax

@example

#include <sys/exceptn.h>

void __djgpp_set_sigint_key(int new_key);

@end example


@subheading Description

This function changes the INTR key that generates the signal
@code{SIGINT}.  By default, @kbd{Ctrl-C} is set as the INTR key.  To
replace it with another key, put the @emph{scan code} of the new INTR
key into the bits 0-7 and the required keyboard status byte into bits
8-15 of @var{new_key}, and call this function.  Here's how the keyboard
status bits are defined:

@example

   Bit
 76543210    Meaning

 .......X    Right Shift key
 ......X.    Left Shift key
 .....X..    Ctrl key
 ....X...    Alt key
 ...X....    Scroll Lock key
 ..X.....    Num Lock key
 .X......    Caps Lock key
 X.......    Insert

@end example

@noindent
A 1 in any of the above bits means that the corresponding key should be
pressed; a zero means it should be released.  Currently, all but the
lower 4 bits are always ignored by the DJGPP keyboard handler when
you set the INTR key using this function.

For example, the default @kbd{Ctrl-C} key should be passed as
@code{0x042e}, since the scan code of the @key{C} key is 2Eh, and when
the @key{Ctrl} key is pressed, the keyboard status byte is 04h.

To disable @code{SIGINT} generation, pass zero as the argument (since no
key has a zero scan code).

This function will set things up so that the left @key{Shift} key
doesn't affect Ctrl- and Alt-modified keys; the right @key{Shift} key
won't affect them either, unless its bit is explicitly set in
@var{new_key}.  This means that @kbd{Ctrl-C} and @kbd{Ctrl-c} will both
trigger @code{SIGINT} if @code{0x042e} is passed to this function.

The DJGPP built-in keyboard handler pretends that when the right
@key{Shift} key is pressed, so is the left @key{Shift} key (but not vice
versa).

For getting similar effects via the POSIX @code{termios} functions, see
@ref{tcsetattr}.

@subheading Return Value

The previous INTR key (scan code in bits 0-7, keyboard status in bits
8-15).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example

  __djgpp_set_sigint_key(0x0422);  /* make Ctrl-g generate SIGINT's */

@end example


@c -----------------------------------------------------------------------------
@node __djgpp_set_sigquit_key, __djgpp_share_flags, __djgpp_set_sigint_key, Alphabetical List
@unnumberedsec __djgpp_set_sigquit_key
@c From file ./go32/dpmiexcp.txh
@findex __djgpp_set_sigquit_key
@subheading Syntax

@example

#include <sys/exceptn.h>

void __djgpp_set_sigquit_key(int new_key);

@end example


@subheading Description

This function changes the QUIT key that generates the signal
@code{SIGQUIT}.  By default, @kbd{Ctrl-\} is set as the QUIT key.  To
replace it with another key, put the @emph{scan code} of the new QUIT
key into the bits 0-7 and the required keyboard status byte into bits
8-15 of @var{new_key}, and call this function.  Here's how the keyboard
status bits are defined:

@example

   Bit
 76543210    Meaning

 .......X    Right Shift key
 ......X.    Left Shift key
 .....X..    Ctrl key
 ....X...    Alt key
 ...X....    Scroll Lock key
 ..X.....    Num Lock key
 .X......    Caps Lock key
 X.......    Insert

@end example

@noindent
A 1 in any of the above bits means that the corresponding key should be
pressed; a zero means it should be released.  Currently, all but the
lower 4 bits are always ignored by the DJGPP keyboard handler when
you set the QUIT key with this function.

For example, the default @kbd{Ctrl-\} key should be passed as
@code{0x042b}, since the scan code of @code{\} is 2Bh and when the
@key{Ctrl} key is pressed, the keyboard status byte is 04h.

To disable @code{SIGQUIT} generation, pass zero as the argument (since
no key has a zero scan code).

This function will set things up so that the left @key{Shift} key
doesn't affect Ctrl- and Alt-modified keys; the right @key{Shift} key
won't affect them either, unless its bit is explicitly set in
@var{new_key}.  This means that @kbd{Ctrl-\} and @kbd{Ctrl-|} will both
trigger @code{SIGQUIT} if @code{0x042b} is passed to this function.

The DJGPP built-in keyboard handler pretends that when the right
@key{Shift} key is pressed, so is the left @key{Shift} key (but not vice
versa).

For getting similar effects via the POSIX @code{termios} functions, see
@ref{tcsetattr}.

@subheading Return Value

The previous QUIT key (scan code in bits 0-7, keyboard status in bits
8-15).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example

  __djgpp_set_sigint_key(0);  /* disable SIGQUIT's */

@end example


@c -----------------------------------------------------------------------------
@node __djgpp_share_flags, __djgpp_spawn, __djgpp_set_sigquit_key, Alphabetical List
@unnumberedsec __djgpp_share_flags
@c From file ./posix/fcntl/open.txh
@findex __djgpp_share_flags

@subheading Syntax

@example
#include <fcntl.h>

int __djgpp_share_flags = ...;
@end example

@subheading Description

This variable controls the share flags used by @code{open} (and hence
@code{fopen}) when opening a file.

If you assign any value other than 0 to this variable libc will use
that value for the sharing bits when if calls DOS to open the file.
But if you specify any share flag in the @code{open} call then these
flags will remain untouched. In this way @code{__djgpp_share_flags}
acts just like a default and by default is 0 ensuring maximum
compatibility with older versions of djgpp.

If you don't know how the share flags act consult any DOS reference. They
allow to share or protect a file when it's opened more than once by the
same task or by two or more tasks. The exact behavior depends on the exact
case. One interesting thing is that when the file is opened by two tasks
under Windows the results are different if you use Windows 3.1 or Windows 95.
To add even more complexity Windows 3.1 is affected by @code{SHARE.EXE}.

The available flags are:

@table @code

@item SH_COMPAT	0x0000

That's the compatible mode.

@item SH_DENYRW	0x0010

Deny read and deny write.

@item SH_DENYWR	0x0020

Deny write.

@item SH_DENYRD	0x0030

Deny read.

@item SH_DENYNO	0x0040

No deny.

@end table

Of course these flags are DOS specific and doesn't exist under other OSs;
and as you can imagine @code{__djgpp_share_flags} is djgpp specific.

@xref{open}.
@xref{fopen}.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __djgpp_spawn, __djgpp_traceback_exit, __djgpp_share_flags, Alphabetical List
@unnumberedsec __djgpp_spawn
@c From file ./dos/process/dosexec.txh
@findex __djgpp_spawn
@subheading Syntax

@example
#include <process.h>

int __djgpp_spawn(int mode, const char *path, char *const argv[],
                  char *const envp[], unsigned long flags);
@end example

@subheading Description

This function runs other programs like @code{spawnve} (@pxref{spawn*}) except
that an additional parameter @var{flags} is passed.  @var{flags} can
include the following flags to control the details of finding the program
to run:

@table @code

@item SPAWN_EXTENSION_SRCH

If an extension is not included in @var{path}, search for a file @var{path}
with the extensions @file{.com}, @file{.exe}, @file{.bat}, and @file{.btm}.

@item SPAWN_NO_EXTENSION_SRCH

Do not perform an extension search.  If the file has an extension, it must
already be included in @var{path}.

@end table

@subheading Return Value

@xref{spawn*}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char *args[] = @{
  "gcc.exe",
  "-v",
  "hello.c",
  0
@};

__djgpp_spawn(P_WAIT, "/dev/env/DJDIR/bin/gcc.exe", args, NULL,
              SPAWN_NO_EXTENSION_SRCH);
@end example


@c -----------------------------------------------------------------------------
@node __djgpp_traceback_exit, _djstat_describe_lossage, __djgpp_spawn, Alphabetical List
@unnumberedsec __djgpp_traceback_exit
@c From file ./go32/dpmiexcp.txh
@findex __djgpp_traceback_exit
@subheading Syntax

@example

#include <signal.h>

void __djgpp_traceback_exit(int signo);

@end example


@subheading Description

This function is a signal handler which will print a traceback and abort
the program.  It is called by default by the DJGPP signal-handling code
when any signal except @code{SIGQUIT} is raised (@code{SIGQUIT} is by
default discarded).

You can use this function to get the Unix behavior of aborting the
program on @code{SIGQUIT} (see the example below).

When this function is called directly, pass the signal number as its
@var{signo} argument.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  signal(SIGQUIT, __djgpp_traceback_exit);
@end example

@c -----------------------------------------------------------------------------
@node _djstat_describe_lossage, _djstat_fail_bits, __djgpp_traceback_exit, Alphabetical List
@unnumberedsec _djstat_describe_lossage
@c From file ./posix/sys/stat/st_loss.txh
@findex _djstat_describe_lossage
@subheading Syntax

@example
#include <stdio.h>

void _djstat_describe_lossage(FILE *fp);
@end example

@subheading Description

Accesses the global variable @code{_djstat_fail_bits}
(@pxref{_djstat_fail_bits}) and prints to the stream
given by @var{fp} a human-readable description of the undocumented
DOS features which the last call to @code{stat()} or @code{fstat()} failed
to use.  (If @var{fp} is zero, the function prints to stderr.)  If the
last call to @code{f?stat()} didn't set any failure bits, an ``all's
well'' message is printed.  This function is designed to help in debugging
these functions in hostile environments (like DOS clones) and in adapting
them to the future DOS versions.  If you ever have any strange results
returned by @code{f?stat()}, please call this function and post the
diagnostics it printed to the DJGPP mailing list.

The diagnostic messages this function prints are almost self-explanatory.
Some explanations of terminology and abbreviations used by the printed
messages will further clarify them.

  SDA (@dfn{Swappable DOS Area}) -- this is an internal DOS structure.
@code{stat()} uses it to get the full directory entry (including the
starting cluster number) of a file.  The pointer to SDA found by
@code{stat()} is trusted only if we find the pathname of our file at a
specific offset in that SDA.

  SFT (@dfn{System File Table}) -- another internal DOS structure, used
in file operations.  @code{fstat()} uses it to get full information on a
file given its handle.  An SFT entry which is found by @code{fstat()} is
only trusted if it contains files size and time stamp like those
returned by DOS functions 57h and 42h.  Novell NetWare 3.x traps DOS
file operations in such a way they never get to SFT, so some failure
messages refer specifically to Novell.

  Hashing -- the fall-back method of returning a unique inode number for
each file.  It is used whenever the starting cluster of a file couldn't be
reliably determined.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  if (stat(path, &stat_buf))
    _djstat_describe_lossage((FILE *)0);
@end example

@c -----------------------------------------------------------------------------
@node _djstat_fail_bits, _djstat_flags, _djstat_describe_lossage, Alphabetical List
@unnumberedsec _djstat_fail_bits
@c From file ./posix/sys/stat/djbits.txh
@vindex _djstat_fail_bits
@subheading Syntax

@example
#include <sys/stat.h>

extern unsigned short   _djstat_fail_bits;
@end example

As proper operation of @code{stat} (@pxref{stat}) and @code{fstat}
(@pxref{fstat}) depend on undocumented DOS features, they could fail in
some incompatible environment or a future DOS version.  If they do, the
@code{_djstat_fail_bits} variable will have some of its bits set.  Each
bit describes a single feature which was used and failed.  The function
@code{_djstat_describe_lossage} (@pxref{_djstat_describe_lossage})
may be called to print a human-readable description of the bits
which were set by the last call to @code{f?stat}.  This should make
debugging @code{f?stat} failures in an unanticipated environment
a lot easier.

The following bits are currently defined:

@table @code

@item _STFAIL_SDA

Indicates that Get SDA call failed.

@item _STFAIL_OSVER

Indicates an unsupported DOS version (less than 3.10 for @code{stat} or
less than 2.0 for @code{fstat}).

@item _STFAIL_BADSDA

The pointer to SDA was found to be bogus.

@item _STFAIL_TRUENAME

Indicates that @code{_truename} (@pxref{_truename}) function call
failed.

@item _STFAIL_HASH

Indicates that the starting cluster of the file is unavailable, and inode
number was computed by hashing its name.

@item _STFAIL_LABEL

The application requested the time stamp of a root dir, but no volume
label was found.

@item _STFAIL_DCOUNT

The number of SDA reported is ridiculously large (probably an unsupported
DOS clone).

@item _STFAIL_WRITEBIT

@code{fstat} was asked to get write access bit of a file, but couldn't.

@item _STFAIL_DEVNO

@code{fstat} failed to get device number.

@item _STFAIL_BADSFT

An SFT entry for this file was found by @code{fstat}, but its contents
can't be trusted because it didn't match file size and time stamp as
reported by DOS.

@item _STFAIL_SFTIDX

The SFT index in Job File Table in program's PSP is negative.

@item _STFAIL_SFTNF

The file entry was not found in the SFT array.

@end table

Below are some explanations of terminology and abbreviations used by the
printed messages, which will further clarify the meaning of the above bits
and their descriptions printed by @code{_djstat_describe_lossage}
(@pxref{_djstat_describe_lossage}).

  SDA (@dfn{Swappable Data Area}) -- this is an internal DOS structure.
@code{stat} uses it to get the full directory entry (including the
starting cluster number) of a file.  The pointer to SDA found by
@code{stat} is trusted only if we find the pathname of our file at a
specific offset in that SDA.

  SFT (@dfn{System File Table}) -- another internal DOS structure, used
in file operations.  @code{fstat} uses it to get full information on a file
given its handle.  An SFT entry which is found by @code{fstat} is only
trusted if it contains files size and time stamp like those returned by
DOS functions 57h and 42h.  Novell NetWare 3.x traps DOS file operations
in such a way they never get to SFT, so some failure messages refer
specifically to Novell.

  Hashing -- the fall-back method of returning a unique inode number for
each file.  It is used whenever the starting cluster of a file couldn't be
reliably determined.  The full pathname of the file is looked up in a
table of files seen earlier (hashing is used to speed the lookup
process).  If found, the inode from the table is returned; this ensures
that a given file will get the same inode number.  Otherwise a new inode
number is invented, recorded in the table and returned to caller.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _djstat_flags, dlclose, _djstat_fail_bits, Alphabetical List
@unnumberedsec _djstat_flags
@c From file ./posix/sys/stat/djbits.txh
@vindex _djstat_flags
@subheading Syntax

@example
#include <sys/stat.h>

extern unsigned short   _djstat_flags;
@end example

This variable contains bits for some fields of @code{struct stat} which are
expensive to compute under DOS.  Any such computation is only done by
@code{stat} (@pxref{stat}) or @code{fstat} (@pxref{fstat}) if the
corresponding bit in @code{_djstat_flags} is @emph{cleared}.  By
default, all the bits are cleared, so applications which don't care,
automagically get a full version, possibly at a price of performance.
To get the fastest possible version for your application, clear
only the bits which you need and set all the others.

The following bits are currently defined:

@table @code

@item _STAT_INODE

Causes @code{stat} and @code{fstat} to compute the @code{st_ino} (inode
number) field.

@item _STAT_EXEC_EXT

Tells @code{stat} and @code{fstat} to compute the execute access bit
from the file-name extension.  @code{stat} and @code{fstat} know about
many popular file-name extensions, to speed up the computation of the
execute access bit.

@item _STAT_EXEC_MAGIC

Tells @code{stat} and @code{fstat} to compute the execute access bit from
magic signature (the first two bytes of the file).  Use
@code{_is_executable} (@pxref{_is_executable}),
if the file-name extension is not enough for this.

Computing the execute access bit from the magic signature is by far the
most expensive part of @code{stat} and @code{fstat} (because it requires
to read the first two bytes of every file).  If your application doesn't
care about execute access bit, setting @code{_STAT_EXEC_MAGIC} will
significantly speed it up.

Note that if @code{_STAT_EXEC_MAGIC} is set, but @code{_STAT_EXEC_EXT}
is not, some files which shouldn't be flagged as executables (e.g., COFF
@file{*.o} object files) will have their execute bit set, because they
have the magic number signature at their beginning.  Therefore, only use
the above combination if you want to debug the list of extensions
provided in @file{is_exec.c} file.

@item _STAT_DIRSIZE

Causes @code{stat} to compute directory size by counting the number of its
entries (unless some friendly network redirector brought a true directory
size with it).  Also computes the number of subdirectories and sets the
number of links @code{st_nlink} field.

This computation is also quite expensive, especially for directories
with large sub-directories.  If your application doesn't care about size
of directories and the @code{st_nlink} member, you should set the
@code{_STAT_DIRSIZE} bit in @code{_djstat_flags}.

@item _STAT_ROOT_TIME

Causes @code{stat} to try to get time stamp of root directory from its
volume label entry, if there is one.

@item _STAT_WRITEBIT

Tells @code{fstat} that file's write access bit is required (this needs
special treatment only under some versions of Novell Netware).

@end table

Note that if you set a bit, some failure bits in
@code{_djstat_fail_bits} (@pxref{_djstat_fail_bits}) might not be set,
because some computations which report failures are only done when they
are required.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node dlclose, dlerror, _djstat_flags, Alphabetical List
@unnumberedsec dlclose
@c From file ./dxe/dlopen.txh
@findex dlclose
@subheading Syntax

@example
#include <dlfcn.h>

int dlclose (void *handle);
@end example

@subheading Description

This function closes a dynamic module loaded with @code{dlopen} 
(@pxref{dlopen}).  The memory is freed and all pointers into that 
image become invalid.

@subheading Return Value

Returns 0 on success, non-zero value on failure.  More detailed
error information can be obtained using @code{dlerror} (@pxref{dlerror}).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable


@c -----------------------------------------------------------------------------
@node dlerror, dlerrstatmod, dlclose, Alphabetical List
@unnumberedsec dlerror
@c From file ./dxe/dlerror.txh
@findex dlerror
@subheading Syntax

@example
#include <dlfcn.h>

char *dlerror (void);
@end example

@subheading Description

This function returns a character string with more information on the
last error that occurred during dynamic linking processing.  

@subheading Return Value

Returns @code{NULL} if no errors, pointer to error string if available.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable


@c -----------------------------------------------------------------------------
@node dlerrstatmod, dlerrstatsym, dlerror, Alphabetical List
@unnumberedsec dlerrstatmod
@c From file ./dxe/dlregsym.txh
@findex dlerrstatmod
@subheading Syntax

@example
#include <sys/dxe.h>

extern void (*dlerrstatmod) (const char *module);
@end example

@subheading Description

This is a pointer to a function (e.g. replaceable) containing a pointer
to a function that is called when static linking fails because of missing
module.  Note that due to delayed nature of static linkage, the error can pop up
very late! If you want to check it at startup, call the "load_MODULENAME"
function explicitly.  The function should never return.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node dlerrstatsym, dlopen, dlerrstatmod, Alphabetical List
@unnumberedsec dlerrstatsym
@c From file ./dxe/dlregsym.txh
@findex dlerrstatsym
@subheading Syntax

@example
#include <sys/dxe.h>

extern void (*dlerrstatsym) (const char *module, const char *symbol);
@end example

@subheading Description

This is a pointer to a function that is being called during static
linking when the dynamic loader finds that some symbol is missing from dynamic
module.  The function should never return.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node dlopen, dlregsym, dlerrstatsym, Alphabetical List
@unnumberedsec dlopen
@c From file ./dxe/dlopen.txh
@findex dlopen
@subheading Syntax

@example
#include <dlfcn.h>

void *dlopen (const char *filename, int mode);
@end example

@subheading Description

This function loads a dynamic executable image, whose file name is
pointed to by @var{filename}, into memory and returns a handle 
associated with the image for use with the @code{dlsym} (@pxref{dlsym})
and @code{dlclose} (@pxref{dlclose}) functions.  

@vindex LD_LIBRARY_PATH

If @var{filename} contains a path it is used, else it searches the path
specified by the environment variable @env{LD_LIBRARY_PATH} and
@env{SYSTEM_DXE_PATH}. DJGPP own search paths are specified in
@env{SYSTEM_DXE_PATH}. User may add additional search path by defining
then in @env{LD_LIBRARY_PATH}. The typical extension used is @file{.DXE},
and these dynamic loadable images are created using
@command{dxe3gen} (@pxref{dxe3gen, , dxe3gen, utils}).

The @var{mode} field is a combination of @code{RTLD_xxx} flags, of which
only @code{RTLD_GLOBAL} works (others are defined in @file{dlfcn.h} for
Unix compatibility).  The @code{RDLD_GLOBAL} flag means all symbols in 
this module are made public and subsequently loaded modules
with unresolved symbols will `see' them and will try to find the unresolved
references through them.

@subheading Return Value

@code{NULL} on failure, handle for the loaded image on success.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable


@c -----------------------------------------------------------------------------
@node dlregsym, dlsym, dlopen, Alphabetical List
@unnumberedsec dlregsym
@c From file ./dxe/dlregsym.txh
@findex dlregsym
@subheading Syntax

@example
#include <sys/dxe.h>

int dlregsym (const dxe_symbol_table *symtab);
@end example

@subheading Description

This function registers a table of symbols to be exported into the
loaded modules.

You can register any number of such tables.  When a module with unresolved
external symbols is loaded, all these tables are searched for the respective
symbol.  If none is found, the last-resort handler is called.  If even the
last-resort handler cannot return an address, an error condition is raised.

The effect of @code{dlregsym} is cumulative.  That is, you can call it
multiple times to register several export symbol tables, and all of them will
be taken into account when loading a new module.

@subheading Return Value

Returns number of symbol tables in use.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node dlsym, _dlsymresolver, dlregsym, Alphabetical List
@unnumberedsec dlsym
@c From file ./dxe/dlopen.txh
@findex dlsym
@subheading Syntax

@example
#include <dlfcn.h>

void *dlsym (void *handle, const char *symbol_name);
@end example

@subheading Description

This function get the address of a symbol defined in a shared loadable
image.  

The @var{handle} argument is the value returned from a call to
@code{dlopen}, or the special value @code{RTLD_DEFAULT} which will
search all symbols in the global scope.

The @var{symbol_name} is the assembler name, not the C name.  For 
DJGPP/COFF prepend an underscore in front.

@subheading Return Value

Returns @code{NULL} on failure, pointer to requested symbol on success.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable


@c -----------------------------------------------------------------------------
@node _dlsymresolver, dlunregsym, dlsym, Alphabetical List
@unnumberedsec _dlsymresolver
@c From file ./dxe/dlregsym.txh
@findex _dlsymresolver
@subheading Syntax

@example
#include <sys/dxe.h>

extern void *(*_dlsymresolver) (const char *symname);
@end example

@subheading Description

This is a pointer to a function (e.g. replaceable) containing a pointer to a
function that is called when an unresolved symbol cannot be found in all
the symbol tables that the dynamic loader have at his disposition.  For
example, as a last resort, the routine could return the address of a dummy
function -- this allows loading modules that you don't know in advance which
unresolved symbols it contains.  Of course, the functions that use this
last-resort dummy function will be, most likely, unuseable but at least you may
query the address of some table inside the module, for example, and process it
somehow.

@subheading Return Value

The handler should return @code{NULL} to rise a error condition, otherwise
it should return a valid address.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node dlunregsym, _doprnt, _dlsymresolver, Alphabetical List
@unnumberedsec dlunregsym
@c From file ./dxe/dlregsym.txh
@findex dlunregsym
@subheading Syntax

@example
#include <sys/dxe.h>

int dlunregsym (const dxe_symbol_table *symtab);
@end example

@subheading Description

This function removes a table of symbols exported into the loaded modules.
For completeness - the inverse of @code{dlregsym} and rarely used.

@subheading Return Value

Returns number of symbol tables in use if success, -1 on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _doprnt, _dos_close, dlunregsym, Alphabetical List
@unnumberedsec _doprnt
@c From file ./ansi/stdio/doprnt.txh
@findex _doprnt
@subheading Syntax

@example
#include <stdio.h>

int _doprnt(const char *format, void *params, FILE *file);
@end example

@subheading Description

This is an internal function that is used by all the @code{printf} style
functions, which simply pass their format, arguments, and stream to this
function. 

@xref{printf}, for a discussion of the allowed formats and arguments. 

@subheading Return Value

The number of characters generated is returned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
int args[] = @{ 1, 2, 3, 66 @};
_doprnt("%d %d %d %c\n", args, stdout);
@end example

@c -----------------------------------------------------------------------------
@node _dos_close, _dos_commit, _doprnt, Alphabetical List
@unnumberedsec _dos_close
@c From file ./dos/compat/d_close.txh
@findex _dos_close
@subheading Syntax

@example
#include <dos.h>

unsigned int _dos_close(int handle);
@end example

@subheading Description

This is a direct connection to the MS-DOS close function call (%ah = 0x3E).
This function closes the specified file.

@xref{_dos_open}. @xref{_dos_creat}. @xref{_dos_creatnew}.
@xref{_dos_read}. @xref{_dos_write}.

@subheading Return Value

Returns 0 if successful or DOS error code on error (and sets @code{errno}).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
int handle;

_dos_creat("FOO.DAT", _A_ARCH, &handle);
...
_dos_close(handle);
@end example
@c -----------------------------------------------------------------------------
@node _dos_commit, _dos_creat, _dos_close, Alphabetical List
@unnumberedsec _dos_commit
@c From file ./dos/compat/d_commit.txh
@findex _dos_commit
@subheading Syntax

@example
#include <dos.h>

unsigned int _dos_commit(int handle);
@end example

@subheading Description

This is a direct connection to the MS-DOS commit function call (%ah = 0x68).
This function flushes DOS internal file buffers to disk.

@subheading Return Value

Returns 0 if successful or DOS error code on error (and sets @code{errno}).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
_dos_write(handle, buffer, 1000, &result);
_dos_commit(handle);
_dos_close(handle);
@end example
@c -----------------------------------------------------------------------------
@node _dos_creat, _dos_creatnew, _dos_commit, Alphabetical List
@unnumberedsec _dos_creat
@c From file ./dos/compat/d_creat.txh
@findex _dos_creat
@subheading Syntax

@example
#include <dos.h>

unsigned int _dos_creat(const char *filename, unsigned short attr,
                        int *handle);
@end example

@subheading Description

This is a direct connection to the MS-DOS creat function call (%ah = 0x3C).
This function creates the given file with the given attribute and puts
file handle into @var{handle} if creating is successful. If the file
already exists it truncates the file to zero length. Meaning of @var{attr}
parameter is the following:

@table @code

@item _A_NORMAL (0x00)

Normal file (no read/write restrictions)

@item _A_RDONLY (0x01)

Read only file

@item _A_HIDDEN (0x02)

Hidden file

@item _A_SYSTEM (0x04)

System file

@item _A_ARCH (0x20)

Archive file

@end table

See also @ref{_dos_open}, @ref{_dos_creatnew}, @ref{_dos_read},
@ref{_dos_write}, and @ref{_dos_close}.

This function does not support long filenames, even on systems where the
LFN API (@pxref{_use_lfn, LFN}) is available.  For LFN-aware functions
with similar functionality see @ref{_creat}, and @ref{_creatnew}.  Also
see @ref{creat}, and @ref{open}, which are Posix-standard.

@subheading Return Value

Returns 0 if successful or DOS error code on error (and sets @code{errno})

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
int handle;

if ( !_dos_creat("FOO.DAT", _A_ARCH, &handle) )
   puts("Creating was successful !");
@end example
@c -----------------------------------------------------------------------------
@node _dos_creatnew, _dos_findfirst, _dos_creat, Alphabetical List
@unnumberedsec _dos_creatnew
@c From file ./dos/compat/d_creatn.txh
@findex _dos_creatnew
@subheading Syntax

@example
#include <dos.h>

unsigned int _dos_creatnew(const char *filename, unsigned short attr,
                           int *handle);
@end example

@subheading Description

This is a direct connection to the MS-DOS create unique function call
(%ah = 0x5B).  This function creates the given file with the given
attribute and puts file handle into @var{handle} if creating is successful.
This function will fail if the specified file exists.  Meaning of
@var{attr} parameter is the following:

@table @code

@item _A_NORMAL (0x00)

Normal file (no read/write restrictions)

@item _A_RDONLY (0x01)

Read only file

@item _A_HIDDEN (0x02)

Hidden file

@item _A_SYSTEM (0x04)

System file

@item _A_ARCH (0x20)

Archive file

@end table

See also @ref{_dos_open}, @ref{_dos_creat}, @ref{_dos_read},
@ref{_dos_write}, and @ref{_dos_close}.

This function does not support long filenames, even on systems where the
LFN API (@pxref{_use_lfn, LFN}) is available.  For LFN-aware functions
with similar functionality see @ref{_creatnew}, and @ref{_creat}.  Also
see @ref{creat}, and @ref{open}, which are Posix-standard.

@subheading Return Value

Returns 0 if successful or DOS error code on error (and sets @code{errno}).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
int handle;

if ( !_dos_creatnew("FOO.DAT", _A_NORMAL, &handle) )
   puts("Creating was successful !");
@end example
@c -----------------------------------------------------------------------------
@node _dos_findfirst, _dos_findnext, _dos_creatnew, Alphabetical List
@unnumberedsec _dos_findfirst
@c From file ./dos/compat/d_findf.txh
@findex _dos_findfirst
@tindex find_t@r{ structure}
@subheading Syntax

@example
#include <dos.h>

unsigned int _dos_findfirst(char *name, unsigned int attr, 
                            struct find_t *result);
@end example

@subheading Description

This function and the related @code{_dos_findnext} (@pxref{_dos_findnext})
are used to scan directories for the list of files therein. The @var{name}
is a wildcard that specifies the directory and files to search. @var{result}
is a structure to hold the results and state of the search, and @var{attr}
is a combination of the following:

@table @code

@item _A_NORMAL (0x00)

Normal file (no read/write restrictions)

@item _A_RDONLY (0x01)

Read only file

@item _A_HIDDEN (0x02)

Hidden file

@item _A_SYSTEM (0x04)

System file

@item _A_VOLID (0x08)

Volume ID file

@item _A_SUBDIR (0x10)

Subdirectory

@item _A_ARCH (0x20)

Archive file

@end table

The results are returned in a @code{struct find_t} defined on
@code{<dos.h>} as follows:

@example
struct find_t @{
  char reserved[21];
  unsigned char attrib;
  unsigned short wr_time;
  unsigned short wr_date;
  unsigned long size;
  char name[256];
@};
@end example

@xref{_dos_findnext}.

This function does not support long filenames, even on systems where the
LFN API (@pxref{_use_lfn, LFN}) is available.  For LFN-aware functions
with similar functionality see @ref{findfirst}, and @ref{findnext}.
Also see @ref{opendir}, and @ref{readdir}, which are Posix-standard.

@subheading Return Value

Zero if a match is found, DOS error code if not found (and sets @code{errno}).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
#include <dos.h>

struct find_t f;

if ( !_dos_findfirst("*.DAT", &f, _A_ARCH | _A_RDONLY) )
@{
  do
  @{
    printf("%-14s %10u %02u:%02u:%02u %02u/%02u/%04u\n",
           f.name,
           f.size,
           (f.wr_time >> 11) & 0x1f,
           (f.wr_time >>  5) & 0x3f,
           (f.wr_time & 0x1f) * 2,
           (f.wr_date >>  5) & 0x0f,
           (f.wr_date & 0x1f),
           ((f.wr_date >> 9) & 0x7f) + 1980);
  @} while( !_dos_findnext(&f) );
@}
@end example
@c -----------------------------------------------------------------------------
@node _dos_findnext, _dos_getdate, _dos_findfirst, Alphabetical List
@unnumberedsec _dos_findnext
@c From file ./dos/compat/d_findn.txh
@findex _dos_findnext
@subheading Syntax

@example
#include <dos.h>

unsigned int _dos_findnext(struct find_t *result);
@end example

@subheading Description

This finds the next file in the search started by @code{_dos_findfirst}.
See @ref{_dos_findfirst}, for the description of @code{struct find_t}.

This function does not support long filenames, even on systems where the
LFN API (@pxref{_use_lfn, LFN}) is available.  For LFN-aware functions
with similar functionality see @ref{findfirst}, and @ref{findnext}.
Also see @ref{opendir}, and @ref{readdir}, which are Posix-standard.

@subheading Return Value

Zero if a match is found, DOS error code if not found (and sets @code{errno}).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _dos_getdate, _dos_getdiskfree, _dos_findnext, Alphabetical List
@unnumberedsec _dos_getdate
@c From file ./dos/compat/d_getdat.txh
@findex _dos_getdate
@tindex dosdate_t@r{ structure}
@subheading Syntax

@example
#include <dos.h>

void _dos_getdate(struct dosdate_t *date);
@end example

@subheading Description

This function gets the current date and fills the @var{date} structure
with these values.

@example
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 */
@};
@end example

@xref{_dos_setdate}. @xref{_dos_gettime}. @xref{_dos_settime}.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
struct dosdate_t date;

_dos_getdate(&date);
@end example
@c -----------------------------------------------------------------------------
@node _dos_getdiskfree, _dos_getdrive, _dos_getdate, Alphabetical List
@unnumberedsec _dos_getdiskfree
@c From file ./dos/compat/d_getdf.txh
@findex _dos_getdiskfree
@tindex diskfree_t@r{ structure}
@subheading Syntax

@example
#include <dos.h>

unsigned int _dos_getdiskfree(unsigned int drive, 
                              struct diskfree_t *diskspace);
@end example

@subheading Description

This function determines the free space on @var{drive} drive
(0=default, 1=A:, 2=B:, etc.) and fills @var{diskspace} structure.
The members of @code{struct diskfree_t} are defined by @code{<dos.h>} as
follows:

@example
struct diskfree_t @{
  unsigned short total_clusters;
  unsigned short avail_clusters;
  unsigned short sectors_per_cluster;
  unsigned short bytes_per_sector;
@};
@end example

@subheading Return Value

Returns with 0 if successful, non-zero on error (and sets @code{errno}
to @code{EINVAL}).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
struct diskfree_t df;
unsigned long freebytes;

if ( !_dos_getdiskfree(0, &df) )
@{
  freebytes = (unsigned long)df.avail_clusters *
              (unsigned long)df.bytes_per_sector *
              (unsigned long)df.sectors_per_cluster;
  printf("There is %lu free bytes on the current drive.\n", freebytes);
@}
else
  printf("Unable to get free disk space.\n");
@end example
@c -----------------------------------------------------------------------------
@node _dos_getdrive, _dos_getfileattr, _dos_getdiskfree, Alphabetical List
@unnumberedsec _dos_getdrive
@c From file ./dos/compat/d_getdrv.txh
@findex _dos_getdrive
@subheading Syntax

@example
#include <dos.h>

void _dos_getdrive(unsigned int *p_drive);
@end example

@subheading Description

This function determine the current default drive and writes this value
into @var{p_drive} (1=A:, 2=B:, etc.).

@xref{_dos_setdrive}.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
unsigned int drive;

_dos_getdrive(&drive);
printf("The current drive is %c:.\n", 'A' - 1 + drive);
@end example
@c -----------------------------------------------------------------------------
@node _dos_getfileattr, _dos_getftime, _dos_getdrive, Alphabetical List
@unnumberedsec _dos_getfileattr
@c From file ./dos/compat/d_getfa.txh
@findex _dos_getfileattr
@subheading Syntax

@example
#include <dos.h>

unsigned int _dos_getfileattr(const char *filename,
                              unsigned int *p_attr);
@end example

@subheading Description

This function determines the attributes of given file and fills @var{attr}
with it. Use the following constants (in DOS.H) to check this value.

@table @code

@item _A_NORMAL (0x00)

Normal file (no read/write restrictions)

@item _A_RDONLY (0x01)

Read only file

@item _A_HIDDEN (0x02)

Hidden file

@item _A_SYSTEM (0x04)

System file

@item _A_VOLID (0x08)

Volume ID file

@item _A_SUBDIR (0x10)

Subdirectory

@item _A_ARCH (0x20)

Archive file

@end table

@xref{_dos_setfileattr}.

This function does not support long filenames, even on systems where the
LFN API (@pxref{_use_lfn, LFN}) is available.  For LFN-aware functions
with similar functionality see @ref{_chmod}.  Also see @ref{chmod},
@ref{access}, and @ref{stat}, which are Posix-standard.

@subheading Return Value

Returns with 0 if successful and DOS error value on error (and sets
@code{errno}=ENOENT).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
unsigned int attr;

if ( !_dos_getfileattr("FOO.DAT", &attr) )
@{
  puts("FOO.DAT attributes are:");
  if ( attr & _A_ARCH )   puts("Archive");
  if ( attr & _A_RDONLY ) puts("Read only");
  if ( attr & _A_HIDDEN ) puts("Hidden");
  if ( attr & _A_SYSTEM ) puts("Is it part of DOS ?");
  if ( attr & _A_VOLID )  puts("Volume ID");
  if ( attr & _A_SUBDIR ) puts("Directory");
@}
else
  puts("Unable to get FOO.DAT attributes.");
@end example
@c -----------------------------------------------------------------------------
@node _dos_getftime, _dos_gettime, _dos_getfileattr, Alphabetical List
@unnumberedsec _dos_getftime
@c From file ./dos/compat/d_getftm.txh
@findex _dos_getftime
@subheading Syntax

@example
#include <dos.h>

unsigned int _dos_getftime(int handle,
                           unsigned int *p_date, unsigned *p_time);
@end example

@subheading Description

This function gets the date and time of the given file and puts these
values into @var{p_date} and @var{p_time} variable. The meaning of
DOS date in the @var{p_date} variable is the following:

@example
F   E   D   C   B   A   9   8   7   6   5   4   3   2   1   0  (bits)
X   X   X   X   X   X   X   X   X   X   X   X   X   X   X   X
*-----------------------*   *-----------*   *---------------*
        year                    month              day

year  = 0-119 (relative to 1980)
month = 1-12
day   = 1-31
@end example

The meaning of DOS time in the @var{p_time} variable is the following:

@example
F   E   D   C   B   A   9   8   7   6   5   4   3   2   1   0
X   X   X   X   X   X   X   X   X   X   X   X   X   X   X   X
*---------------*   *-------------------*   *---------------*
      hours              minutes                seconds

hours   = 0-23
minutes = 0-59
seconds = 0-29 in two-second intervals
@end example

@xref{_dos_setftime}.

This function cannot be used to return last access and creation date and
time, even on systems where the LFN API (@pxref{_use_lfn, LFN}) is
available.  See @ref{_lfn_get_ftime}, for a function that can be used to
get the other two times.  Also see @ref{fstat}, which is Posix-standard.

@subheading Return Value

Returns 0 if successful and return DOS error on error (and sets
@code{errno}=EBADF).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
unsigned int handle, date, time;

_dos_open("FOO.DAT", O_RDWR, &handle);
_dos_getftime(handle, &date, &time);
_dos_close(handle);
printf("FOO.DAT date and time is: %04u-%02u-%02u %02u:%02u:%02u.\n",
       /*       year                      month              day    */
       ((date >> 9) & 0x7F) + 1980U, (date >>  5) & 0x0F, date & 0x1F,
       /*       hour                minute           second         */
       (time >> 11) & 0x1F, (time >>  5) & 0x3F, (time & 0x1F) * 2);
@end example
@c -----------------------------------------------------------------------------
@node _dos_gettime, _dos_lk64, _dos_getftime, Alphabetical List
@unnumberedsec _dos_gettime
@c From file ./dos/compat/d_gettim.txh
@findex _dos_gettime
@tindex dostime_t@r{ structure}
@subheading Syntax

@example
#include <dos.h>

void _dos_gettime(struct dostime_t *time);
@end example

@subheading Description

This function gets the current time and fills the @var{time} structure
with these values.

@example
struct dostime_t @{
  unsigned char hour;     /* 0-23 */
  unsigned char minute;   /* 0-59 */
  unsigned char second;   /* 0-59 */
  unsigned char hsecond;  /* 0-99 */
@};
@end example

@xref{_dos_settime}. @xref{_dos_getdate}. @xref{_dos_setdate}.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
struct dostime_t time;

_dos_gettime(&time);
@end example
@c -----------------------------------------------------------------------------
@node _dos_lk64, _dos_lock, _dos_gettime, Alphabetical List
@unnumberedsec _dos_lk64
@c From file ./dos/io/doslk64.txh
@findex _dos_lk64
@subheading Syntax

@example
#include <io.h>

int _dos_lk64(int fd, long long offset, long long length);
@end example

@subheading Description

Adds an advisory lock to the specified region of the file.

Arguments @var{offset} and @var{length} must be of type @code{long
long}, thus enabling you to lock with offsets and lengths as large as
~@math{2^63} (FAT16 limits this to ~@math{2^31}; FAT32 limits this to
@math{2^32-2}).

@xref{_dos_unlk64}.

@subheading Return Value

Zero if the lock was added, nonzero otherwise.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _dos_lock, _dos_open, _dos_lk64, Alphabetical List
@unnumberedsec _dos_lock
@c From file ./dos/io/doslock.txh
@findex _dos_lock
@subheading Syntax

@example
#include <io.h>

int _dos_lock(int fd, long offset, long length);
@end example

@subheading Description

Adds an advisory lock to the specified region of the file.

@subheading Return Value

Zero if the lock was added, nonzero otherwise.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _dos_open, _dos_read, _dos_lock, Alphabetical List
@unnumberedsec _dos_open
@c From file ./dos/compat/d_open.txh
@findex _dos_open
@subheading Syntax

@example
#include <fcntl.h>
#include <share.h>
#include <dos.h>

unsigned int _dos_open(const char *filename, unsigned short mode,
                       int *handle);
@end example

@subheading Description

This is a direct connection to the MS-DOS open function call (%ah = 0x3D).
This function opens the given file with the given mode and puts handle of
file into @var{handle} if opening is successful.
Meaning of @var{mode} parameter is the following:

Access mode bits (in FCNTL.H):
@table @code

@item O_RDONLY (_O_RDONLY) 0x00

Open for read only

@item O_WRONLY (_O_WRONLY) 0x01

Open for write only

@item O_RDWR (_O_RDWR) 0x02

Open for read and write

@end table

Sharing mode bits (in SHARE.H):
@table @code

@item SH_COMPAT (_SH_COMPAT) 0x00

Compatibility mode

@item SH_DENYRW (_SH_DENYRW) 0x10

Deny read/write mode

@item SH_DENYWR (_SH_DENYWR) 0x20

Deny write mode

@item SH_DENYRD (_SH_DENYRD) 0x30

Deny read mode

@item SH_DENYNO (_SH_DENYNO) 0x40

Deny none mode

@end table

Inheritance bits (in FCNTL.H):
@table @code

@item O_NOINHERIT (_O_NOINHERIT) 0x80

File is not inherited by child process

@end table

See also @ref{_dos_creat}, @ref{_dos_creatnew}, @ref{_dos_read},
@ref{_dos_write}, and @ref{_dos_close}.

This function does not support long filenames, even on systems where the
LFN API (@pxref{_use_lfn, LFN}) is available.  For LFN-aware functions
with similar functionality see @ref{_open}, @ref{_creat}, and
@ref{_creatnew}.  Also see @ref{open}, and @ref{creat}, which are
Posix-standard.

@subheading Return Value

Returns 0 if successful or DOS error code on error (and sets
@code{errno} to EACCES, EINVAL, EMFILE or ENOENT).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
int handle;

if ( !_dos_open("FOO.DAT", O_RDWR, &handle) )
   puts("Wow, file opening was successful !");
@end example
@c -----------------------------------------------------------------------------
@node _dos_read, _dos_setdate, _dos_open, Alphabetical List
@unnumberedsec _dos_read
@c From file ./dos/compat/d_read.txh
@findex _dos_read
@subheading Syntax

@example
#include <dos.h>

unsigned int _dos_read(int handle, void *buffer, unsigned int count,
                       unsigned int *result);
@end example

@subheading Description

This is a direct connection to the MS-DOS read function call (%ah = 0x3F).
No conversion is done on the data; it is read as raw binary data.  This
function reads from @var{handle} into @var{buffer} @var{count} bytes.
@var{count} value may be arbitrary size (for example > 64KB).  It puts
number of bytes read into @var{result} if reading is successful.

See also @ref{_dos_open}, @ref{_dos_creat}, @ref{_dos_creatnew},
@ref{_dos_write}, and @ref{_dos_close}.

@subheading Return Value

Returns 0 if successful or DOS error code on error (and sets @code{errno}
to EACCES or EBADF)

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
int handle;
unsigned int result;
char *filebuffer;

if ( !_dos_open("FOO.DAT", O_RDONLY, &handle) )
@{
   puts("FOO.DAT opening was successful.");
   if ( (filebuffer = malloc(130000)) != NULL )
   @{
     if ( !_dos_read(handle, buffer, 130000, &result) )
       printf("%u bytes read from FOO.DAT.\n", result);
     else
       puts("Reading error.");
     ...
     /* Do something with filebuffer. */
     ...
   @}
   _dos_close(handle);
@}
@end example
@c -----------------------------------------------------------------------------
@node _dos_setdate, _dos_setdrive, _dos_read, Alphabetical List
@unnumberedsec _dos_setdate
@c From file ./dos/compat/d_setdat.txh
@findex _dos_setdate
@subheading Syntax

@example
#include <dos.h>

unsigned int _dos_setdate(struct dosdate_t *date);
@end example

@subheading Description

This function sets the current date. The @var{dosdate_t} structure
is as follows:

@example
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 */
@};
@end example

@var{dayofweek} field has no effect at this function call.

@xref{_dos_getdate}. @xref{_dos_gettime}. @xref{_dos_settime}.

@subheading Return Value

Returns 0 if successful and non-zero on error (and sets @code{errno}=EINVAL).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
struct dosdate_t date;

date->year  = 1999;
date->month = 12;
date->day   = 31;
if ( !_dos_setdate(&date) )
  puts("It was a valid date.");
@end example

@c -----------------------------------------------------------------------------
@node _dos_setdrive, _dos_setfileattr, _dos_setdate, Alphabetical List
@unnumberedsec _dos_setdrive
@c From file ./dos/compat/d_setdrv.txh
@findex _dos_setdrive
@subheading Syntax

@example
#include <dos.h>

void _dos_setdrive(unsigned int drive, unsigned int *p_drives);
@end example

@subheading Description

This function set the current default drive based on @var{drive}
(1=A:, 2=B:, etc.) and determines the number of available logical
drives and fills @var{p_drives} with it.

@xref{_dos_getdrive}.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
unsigned int available_drives;

/* The current drive will be A: */
_dos_setdrive(1, &available_drives);
printf("Number of available logical drives %u.\n", available_drives);
@end example
@c -----------------------------------------------------------------------------
@node _dos_setfileattr, _dos_setftime, _dos_setdrive, Alphabetical List
@unnumberedsec _dos_setfileattr
@c From file ./dos/compat/d_setfa.txh
@findex _dos_setfileattr
@subheading Syntax

@example
#include <dos.h>

unsigned int _dos_setfileattr(const char *filename, unsigned int attr);
@end example

@subheading Description

This function sets the attributes of given file. Use the following
constants in DOS.H to create @var{attr} parameter:

@table @code

@item _A_NORMAL (0x00)

Normal file (no read/write restrictions)

@item _A_RDONLY (0x01)

Read only file

@item _A_HIDDEN (0x02)

Hidden file

@item _A_SYSTEM (0x04)

System file

@item _A_VOLID (0x08)

Volume ID file

@item _A_SUBDIR (0x10)

Subdirectory

@item _A_ARCH (0x20)

Archive file

@end table

@xref{_dos_getfileattr}.

This function does not support long filenames, even on systems where the
LFN API (@pxref{_use_lfn, LFN}) is available.  For LFN-aware functions
with similar functionality see @ref{_chmod}.  Also see @ref{chmod}, which
is Posix-standard.

@subheading Return Value

Returns with 0 if successful and DOS error value on error (and sets
@code{errno} to ENOENT or EACCES).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
if ( !_dos_setfileattr("FOO.DAT", _A_RDONLY | _A_HIDDEN) )
   puts("FOO.DAT is hidden now.");
@end example
@c -----------------------------------------------------------------------------
@node _dos_setftime, _dos_settime, _dos_setfileattr, Alphabetical List
@unnumberedsec _dos_setftime
@c From file ./dos/compat/d_setftm.txh
@findex _dos_setftime
@subheading Syntax

@example
#include <dos.h>

unsigned int _dos_setftime(int handle,
                           unsigned int date, unsigned time);
@end example

@subheading Description

This function sets the date and time of the given file. The meaning
of DOS date in the @var{date} variable is the following:

@example
F E D C B A 9 8 7 6 5 4 3 2 1 0 (bits)
x x x x x x x x x x x x x x x x
*-----------* *-----* *-------*
    year       month     day

year  = 0-119 (relative to 1980)
month = 1-12
day   = 1-31
@end example

The meaning of DOS time in the @var{time} variable is the following:

@example
F E D C B A 9 8 7 6 5 4 3 2 1 0 (bits)
x x x x x x x x x x x x x x x x
*-------* *---------* *-------*
  hours     minutes    seconds

hours   = 0-23
minutes = 0-59
seconds = 0-29 in two-second intervals
@end example

@xref{_dos_getftime}.

This function cannot be used to set the last access date and time, even
on systems where the LFN API (@pxref{_use_lfn, LFN}) is available.  For
LFN-aware functions with similar functionality see @ref{utime}, which is
Posix-standard, and see @ref{utimes}.

@subheading Return Value

Returns 0 if successful and return DOS error on error (and sets
@code{errno}=EBADF).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
struct dosdate_t d;
struct dostime_t t;
unsigned int handle, date, time;

_dos_open("FOO.DAT", O_RDWR, &handle);
_dos_getdate(&d);
_dos_gettime(&t);
date = ((d.year - 1980) << 9) | (d.month << 5) | d.day;
time = (t.hour << 11) | (t.minute << 5) | (t.second / 2);
_dos_setftime(handle, date, time);
_dos_close(handle);
@end example
@c -----------------------------------------------------------------------------
@node _dos_settime, _dos_unlk64, _dos_setftime, Alphabetical List
@unnumberedsec _dos_settime
@c From file ./dos/compat/d_settim.txh
@findex _dos_settime
@subheading Syntax

@example
#include <dos.h>

void _dos_settime(struct dostime_t *time);
@end example

@subheading Description

This function sets the current time. The @var{time} structure
is as follows:

@example
struct dostime_t @{
  unsigned char hour;     /* 0-23 */
  unsigned char minute;   /* 0-59 */
  unsigned char second;   /* 0-59 */
  unsigned char hsecond;  /* 0-99 */
@};
@end example

@xref{_dos_gettime}. @xref{_dos_getdate}. @xref{_dos_setdate}.

@subheading Return Value

Returns 0 if successful and non-zero on error (and sets @code{errno}=EINVAL).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
struct dostime_t time;

time->hour    = 23;
time->minute  = 59;
time->second  = 59;
time->hsecond = 99;
if ( !_dos_settime(&time) )
  puts("It was a valid time.");
@end example
@c -----------------------------------------------------------------------------
@node _dos_unlk64, _dos_unlock, _dos_settime, Alphabetical List
@unnumberedsec _dos_unlk64
@c From file ./dos/io/dosunl64.txh
@findex _dos_unlk64
@subheading Syntax

@example
#include <io.h>

int _dos_unlk64(int fd, long long offset, long long length);
@end example

@subheading Description

Removes an advisory lock to the specified region of the file.

Arguments @var{offset} and @var{length} must be of type @code{long
long}, thus enabling you to unlock with offsets and lengths as large as
~@math{2^63} (FAT16 limits this to ~@math{2^31}; FAT32 limits this to
@math{2^32-2}).

@xref{_dos_lk64}.

@subheading Return Value

Zero if the lock was removed, nonzero otherwise.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _dos_unlock, _dos_write, _dos_unlk64, Alphabetical List
@unnumberedsec _dos_unlock
@c From file ./dos/io/dosunloc.txh
@findex _dos_unlock
@subheading Syntax

@example
#include <io.h>

_dos_unlock(int fd, long offset, long length);
@end example

@subheading Description

Removes an advisory lock to the specified region of the file.

@subheading Return Value

Zero if the lock was removed, nonzero otherwise.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _dos_write, _doscan, _dos_unlock, Alphabetical List
@unnumberedsec _dos_write
@c From file ./dos/compat/d_write.txh
@findex _dos_write
@subheading Syntax

@example
#include <dos.h>

unsigned int _dos_write(int handle,
                        const void *buffer, unsigned int count,
                        unsigned int *result);
@end example

@subheading Description

This is a direct connection to the MS-DOS write function call (%ah = 0x40).
No conversion is done on the data; it is written as raw binary data.  This
function writes @var{count} bytes from @var{buffer} to @var{handle}.
@var{count} value may be arbitrary size (e.g. > 64KB).  It puts the
number of bytes written into @var{result} if writing is successful.

See also @ref{_dos_open}, @ref{_dos_creat}, @ref{_dos_creatnew},
@ref{_dos_read}, and @ref{_dos_close}.

@subheading Return Value

Returns 0 if successful or DOS error code on error (and sets @code{errno}
to EACCES or EBADF)

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
int handle;
unsigned int result;
char *filebuffer;

if ( !_dos_creat("FOO.DAT", _A_ARCH, &handle) )
@{
   puts("FOO.DAT creating was successful.");
   if ( (filebuffer = malloc(130000)) != NULL )
   @{
     ...
     /* Put something into filebuffer. */
     ...
     if ( !_dos_write(handle, buffer, 130000, &result) )
       printf("%u bytes written into FOO.DAT.", result);
     else
       puts("Writing error.");
   @}
   _dos_close(handle);
@}
@end example
@c -----------------------------------------------------------------------------
@node _doscan, _doserrno, _dos_write, Alphabetical List
@unnumberedsec _doscan
@c From file ./ansi/stdio/doscan.txh
@findex _doscan
@subheading Syntax

@example
#include <stdarg.h>
#include <stdio.h>

int _doscan(FILE *file, const char *format, va_list argp);
@end example

@subheading Description

This is an internal function that is used by all the @code{scanf} style
functions, which simply pass their format, arguments, and stream to this
function. 

@xref{scanf}, for a discussion of the allowed formats and arguments. 

@subheading Return Value

The number of characters successfully scanned is returned, or -1 on
error. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
TODO: This example is bogus now!
TODO: Rewrite this example!

int x, y;
int *args[2];
args[0] = &x;
args[1] = &y;
_doscan(stdin, "%d %d", args);
@end example

@c -----------------------------------------------------------------------------
@node _doserrno, __dosexec_find_on_path, _doscan, Alphabetical List
@unnumberedsec _doserrno
@c From file ./dos/errno/doserrno.txh
@vindex _doserrno
@subheading Syntax
 
@example
#include <errno.h>
 
extern int _doserrno;
@end example
 
@subheading Description

Whenever a DOS call returns a failure indication, this variable is
assigned the value of the error code returned by the failed DOS call.

For a list of the error codes and their short descriptions, see
@ref{dosexterr}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
 _doserrno = 0;
 fprintf (stdprn, "Hello, world!\r\n\f");
 if (_doserrno == 0x1c)
   fprintf (stderr, "The printer is out of paper!\n");
@end example
@c -----------------------------------------------------------------------------
@node __dosexec_find_on_path, dosexterr, _doserrno, Alphabetical List
@unnumberedsec __dosexec_find_on_path
@c From file ./dos/process/dosexec.txh
@findex __dosexec_find_on_path
@subheading Syntax

@example
#include <stdio.h>
#include <libc/dosexec.h>

char *__dosexec_find_on_path(const char *program,
                             char *envp[], char *buf);
@end example

@subheading Description

This function searches for a program using a given path.  The program is
searched for using a known set of executable extensions, e.g. @file{.exe}.
These executable extensions are described for the @code{spawn*()} function
(@pxref{spawn*}).

Pass the program name in @var{program}, the environment array in
@var{envp} and the output buffer in @var{buf}.  @var{envp} is an array
of pointers to the environment variables; it must be terminated with a
@code{NULL} pointer.  @var{buf} must be large enough to hold at least
@samp{FILENAME_MAX} bytes.

@var{envp} controls where @code{__dosexec_find_on_path} looks for the
program.  If @var{envp} is @code{NULL}, then only the current directory
is searched.  If @var{envp} contains the @samp{PATH} environment
variable whose value lists several directories, then these directories
are also searched.  The global variable @code{environ} is usually passed
for @var{envp}.

@subheading Return Value

If the function finds the program, with or without one of the known
executable extensions, either in the current directory or along
the @samp{PATH} as recorded in @var{envp}, it puts the full pathname
into @var{buf} and returns a pointer to @var{buf}.  Otherwise, it returns
@code{NULL}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@smallexample
 char shellpath[FILENAME_MAX];
 extern char * __dosexec_find_on_path (const char *, char *[], char *);
 extern char **environ;

 /* See if we can find "/bin/sh.exe", "/bin/sh.com", etc.  */
 if (__dosexec_find_on_path ("/bin/sh", (char **)0, shellpath)
     /* If not found, look for "sh" along the PATH.  */
     || __dosexec_find_on_path ("sh", environ, shellpath))
   printf ("/bin/sh found as `%s'\n", shellpath);
@end smallexample
@c -----------------------------------------------------------------------------
@node dosexterr, dosmemget, __dosexec_find_on_path, Alphabetical List
@unnumberedsec dosexterr
@c From file ./dos/compat/d_exterr.txh
@findex dosexterr
@tindex DOSERROR@r{ structure}
@subheading Syntax

@example
#include <dos.h>

int dosexterr(struct DOSERROR *p_error);
@end example

@subheading Description

This function reads extended error information from DOS and fills
@var{p_error} structure.

@example
struct DOSERROR @{
  int  exterror;
  char class;
  char action;
  char locus;
@};
@end example

Values for DOS extended error code (@var{exterr} field):
@example
---DOS 2.0+ ---
 00h (0)   no error
 01h (1)   function number invalid
 02h (2)   file not found
 03h (3)   path not found
 04h (4)   too many open files (no handles available)
 05h (5)   access denied
 06h (6)   invalid handle
 07h (7)   memory control block destroyed
 08h (8)   insufficient memory
 09h (9)   memory block address invalid
 0Ah (10)  environment invalid (usually >32K in length)
 0Bh (11)  format invalid
 0Ch (12)  access code invalid
 0Dh (13)  data invalid
 0Eh (14)  reserved
 0Eh (14)  (PTS-DOS 6.51+, S/DOS 1.0+) fixup overflow
 0Fh (15)  invalid drive
 10h (16)  attempted to remove current directory
 11h (17)  not same device
 12h (18)  no more files
---DOS 3.0+ (INT 24 errors)---
 13h (19)  disk write-protected
 14h (20)  unknown unit
 15h (21)  drive not ready
 16h (22)  unknown command
 17h (23)  data error (CRC)
 18h (24)  bad request structure length
 19h (25)  seek error
 1Ah (26)  unknown media type (non-DOS disk)
 1Bh (27)  sector not found
 1Ch (28)  printer out of paper
 1Dh (29)  write fault
 1Eh (30)  read fault
 1Fh (31)  general failure
 20h (32)  sharing violation
 21h (33)  lock violation
 22h (34)  disk change invalid (ES:DI -> media ID structure)(see #01681)
 23h (35)  FCB unavailable
 23h (35)  (PTS-DOS 6.51+, S/DOS 1.0+) bad FAT
 24h (36)  sharing buffer overflow
 25h (37)  (DOS 4.0+) code page mismatch
 26h (38)  (DOS 4.0+) cannot complete file operation (EOF / out of input)
 27h (39)  (DOS 4.0+) insufficient disk space
 28h-31h   reserved
---OEM network errors (INT 24)---
 32h (50)  network request not supported
 33h (51)  remote computer not listening
 34h (52)  duplicate name on network
 35h (53)  network name not found
 36h (54)  network busy
 37h (55)  network device no longer exists
 38h (56)  network BIOS command limit exceeded
 39h (57)  network adapter hardware error
 3Ah (58)  incorrect response from network
 3Bh (59)  unexpected network error
 3Ch (60)  incompatible remote adapter
 3Dh (61)  print queue full
 3Eh (62)  queue not full
 3Fh (63)  not enough space to print file
 40h (64)  network name was deleted
 41h (65)  network: Access denied
         (DOS 3.0+ [maybe 3.3+???]) codepage switching not possible
           (see also INT 21/AX=6602h,INT 2F/AX=AD42h)
 42h (66)  network device type incorrect
 43h (67)  network name not found
 44h (68)  network name limit exceeded
 45h (69)  network BIOS session limit exceeded
 46h (70)  temporarily paused
 47h (71)  network request not accepted
 48h (72)  network print/disk redirection paused
 49h (73)  network software not installed
           (LANtastic) invalid network version
 4Ah (74)  unexpected adapter close
           (LANtastic) account expired
 4Bh (75)  (LANtastic) password expired
 4Ch (76)  (LANtastic) login attempt invalid at this time
 4Dh (77)  (LANtastic v3+) disk limit exceeded on network node
 4Eh (78)  (LANtastic v3+) not logged in to network node
 4Fh (79)  reserved
---end of errors reportable via INT 24---
 50h (80)  file exists
 51h (81)  (undoc) duplicated FCB
 52h (82)  cannot make directory
 53h (83)  fail on INT 24h
---network-related errors (non-INT 24)---
 54h (84)  (DOS 3.3+) too many redirections / out of structures
 55h (85)  (DOS 3.3+) duplicate redirection / already assigned
 56h (86)  (DOS 3.3+) invalid password
 57h (87)  (DOS 3.3+) invalid parameter
 58h (88)  (DOS 3.3+) network write fault
 59h (89)  (DOS 4.0+) function not supported on network / no process slots
             available
 5Ah (90)  (DOS 4.0+) required system component not installed / not frozen
 5Bh (91)  (DOS 4.0+,NetWare4) timer server table overflowed
 5Ch (92)  (DOS 4.0+,NetWare4) duplicate in timer service table
 5Dh (93)  (DOS 4.0+,NetWare4) no items to work on
 5Fh (95)  (DOS 4.0+,NetWare4) interrupted / invalid system call
 64h (100) (MSCDEX) unknown error
 64h (100) (DOS 4.0+,NetWare4) open semaphore limit exceeded
 65h (101) (MSCDEX) not ready
 65h (101) (DOS 4.0+,NetWare4) exclusive semaphore is already owned
 66h (102) (MSCDEX) EMS memory no longer valid
 66h (102) (DOS 4.0+,NetWare4) semaphore was set when close attempted
 67h (103) (MSCDEX) not High Sierra or ISO-9660 format
 67h (103) (DOS 4.0+,NetWare4) too many exclusive semaphore requests
 68h (104) (MSCDEX) door open
 68h (104) (DOS 4.0+,NetWare4) operation invalid from interrupt handler
 69h (105) (DOS 4.0+,NetWare4) semaphore owner died
 6Ah (106) (DOS 4.0+,NetWare4) semaphore limit exceeded
 6Bh (107) (DOS 4.0+,NetWare4) insert drive B: disk into A: / disk changed
 6Ch (108) (DOS 4.0+,NetWare4) drive locked by another process
 6Dh (109) (DOS 4.0+,NetWare4) broken pipe
 6Eh (110) (DOS 5.0+,NetWare4) pipe open/create failed
 6Fh (111) (DOS 5.0+,NetWare4) pipe buffer overflowed
 70h (112) (DOS 5.0+,NetWare4) disk full
 71h (113) (DOS 5.0+,NetWare4) no more search handles
 72h (114) (DOS 5.0+,NetWare4) invalid target handle for dup2
 73h (115) (DOS 5.0+,NetWare4) bad user virtual address / protection violation
 74h (116) (DOS 5.0+) VIOKBD request
 74h (116) (NetWare4) error on console I/O
 75h (117) (DOS 5.0+,NetWare4) unknown category code for IOCTL
 76h (118) (DOS 5.0+,NetWare4) invalid value for verify flag
 77h (119) (DOS 5.0+,NetWare4) level four driver not found by DOS IOCTL
 78h (120) (DOS 5.0+,NetWare4) invalid / unimplemented function number
 79h (121) (DOS 5.0+,NetWare4) semaphore timeout
 7Ah (122) (DOS 5.0+,NetWare4) buffer too small to hold return data
 7Bh (123) (DOS 5.0+,NetWare4) invalid character or bad file-system name
 7Ch (124) (DOS 5.0+,NetWare4) unimplemented information level
 7Dh (125) (DOS 5.0+,NetWare4) no volume label found
 7Eh (126) (DOS 5.0+,NetWare4) module handle not found
 7Fh (127) (DOS 5.0+,NetWare4) procedure address not found
 80h (128) (DOS 5.0+,NetWare4) CWait found no children
 81h (129) (DOS 5.0+,NetWare4) CWait children still running
 82h (130) (DOS 5.0+,NetWare4) invalid operation for direct disk-access handle
 83h (131) (DOS 5.0+,NetWare4) attempted seek to negative offset
 84h (132) (DOS 5.0+,NetWare4) attempted to seek on device or pipe
---JOIN/SUBST errors---
 85h (133) (DOS 5.0+,NetWare4) drive already has JOINed drives
 86h (134) (DOS 5.0+,NetWare4) drive is already JOINed
 87h (135) (DOS 5.0+,NetWare4) drive is already SUBSTed
 88h (136) (DOS 5.0+,NetWare4) can not delete drive which is not JOINed
 89h (137) (DOS 5.0+,NetWare4) can not delete drive which is not SUBSTed
 8Ah (138) (DOS 5.0+,NetWare4) can not JOIN to a JOINed drive
 8Bh (139) (DOS 5.0+,NetWare4) can not SUBST to a SUBSTed drive
 8Ch (140) (DOS 5.0+,NetWare4) can not JOIN to a SUBSTed drive
 8Dh (141) (DOS 5.0+,NetWare4) can not SUBST to a JOINed drive
 8Eh (142) (DOS 5.0+,NetWare4) drive is busy
 8Fh (143) (DOS 5.0+,NetWare4) can not JOIN/SUBST to same drive
 90h (144) (DOS 5.0+,NetWare4) directory must not be root directory
 91h (145) (DOS 5.0+,NetWare4) can only JOIN to empty directory
 92h (146) (DOS 5.0+,NetWare4) path is already in use for SUBST
 93h (147) (DOS 5.0+,NetWare4) path is already in use for JOIN
 94h (148) (DOS 5.0+,NetWare4) path is in use by another process
 95h (149) (DOS 5.0+,NetWare4) directory previously SUBSTituted
 96h (150) (DOS 5.0+,NetWare4) system trace error
 97h (151) (DOS 5.0+,NetWare4) invalid event count for DosMuxSemWait
 98h (152) (DOS 5.0+,NetWare4) too many waiting on mutex
 99h (153) (DOS 5.0+,NetWare4) invalid list format
 9Ah (154) (DOS 5.0+,NetWare4) volume label too large
 9Bh (155) (DOS 5.0+,NetWare4) unable to create another TCB
 9Ch (156) (DOS 5.0+,NetWare4) signal refused
 9Dh (157) (DOS 5.0+,NetWare4) segment discarded
 9Eh (158) (DOS 5.0+,NetWare4) segment not locked
 9Fh (159) (DOS 5.0+,NetWare4) invalid thread-ID address
-----
 A0h (160) (DOS 5.0+) bad arguments
 A0h (160) (NetWare4) bad environment pointer
 A1h (161) (DOS 5.0+,NetWare4) invalid pathname passed to EXEC
 A2h (162) (DOS 5.0+,NetWare4) signal already pending
 A3h (163) (DOS 5.0+) uncertain media
 A3h (163) (NetWare4) ERROR_124 mapping
 A4h (164) (DOS 5.0+) maximum number of threads reached
 A4h (164) (NetWare4) no more process slots
 A5h (165) (NetWare4) ERROR_124 mapping
 B0h (176) (MS-DOS 7.0) volume is not locked
 B1h (177) (MS-DOS 7.0) volume is locked in drive
 B2h (178) (MS-DOS 7.0) volume is not removable
 B4h (180) (MS-DOS 7.0) lock count has been exceeded
 B4h (180) (NetWare4) invalid segment number
 B5h (181) (MS-DOS 7.0) a valid eject request failed
 B5h (181) (DOS 5.0-6.0,NetWare4) invalid call gate
 B6h (182) (DOS 5.0+,NetWare4) invalid ordinal
 B7h (183) (DOS 5.0+,NetWare4) shared segment already exists
 B8h (184) (DOS 5.0+,NetWare4) no child process to wait for
 B9h (185) (DOS 5.0+,NetWare4) NoWait specified and child still running
 BAh (186) (DOS 5.0+,NetWare4) invalid flag number
 BBh (187) (DOS 5.0+,NetWare4) semaphore does not exist
 BCh (188) (DOS 5.0+,NetWare4) invalid starting code segment
 BDh (189) (DOS 5.0+,NetWare4) invalid stack segment
 BEh (190) (DOS 5.0+,NetWare4) invalid module type (DLL can not be used as
             application)
 BFh (191) (DOS 5.0+,NetWare4) invalid EXE signature
 C0h (192) (DOS 5.0+,NetWare4) EXE marked invalid
 C1h (193) (DOS 5.0+,NetWare4) bad EXE format (e.g. DOS-mode program)
 C2h (194) (DOS 5.0+,NetWare4) iterated data exceeds 64K
 C3h (195) (DOS 5.0+,NetWare4) invalid minimum allocation size
 C4h (196) (DOS 5.0+,NetWare4) dynamic link from invalid Ring
 C5h (197) (DOS 5.0+,NetWare4) IOPL not enabled
 C6h (198) (DOS 5.0+,NetWare4) invalid segment descriptor privilege level
 C7h (199) (DOS 5.0+,NetWare4) automatic data segment exceeds 64K
 C8h (200) (DOS 5.0+,NetWare4) Ring2 segment must be moveable
 C9h (201) (DOS 5.0+,NetWare4) relocation chain exceeds segment limit
 CAh (202) (DOS 5.0+,NetWare4) infinite loop in relocation chain
 CBh (203) (NetWare4) environment variable not found
 CCh (204) (NetWare4) not current country
 CDh (205) (NetWare4) no signal sent
 CEh (206) (NetWare4) file name not 8.3
 CFh (207) (NetWare4) Ring2 stack in use
 D0h (208) (NetWare4) meta expansion is too long
 D1h (209) (NetWare4) invalid signal number
 D2h (210) (NetWare4) inactive thread
 D3h (211) (NetWare4) file system information not available
 D4h (212) (NetWare4) locked error
 D5h (213) (NetWare4) attempted to execute non-family API call in DOS mode
 D6h (214) (NetWare4) too many modules
 D7h (215) (NetWare4) nesting not allowed
 E6h (230) (NetWare4) non-existent pipe, or bad operation
 E7h (231) (NetWare4) pipe is busy
 E8h (232) (NetWare4) no data available for nonblocking read
 E9h (233) (NetWare4) pipe disconnected by server
 EAh (234) (NetWare4) more data available
 FFh (255) (NetWare4) invalid drive
@end example

Values for error class (@var{class} field):
@example
 01h (1)  out of resource (storage space or I/O channels)
 02h (2)  temporary situation (file or record lock)
 03h (3)  authorization / permission problem (denied access)
 04h (4)  internal system error (system software bug)
 05h (5)  hardware failure
 06h (6)  system failure (configuration file missing or incorrect)
 07h (7)  application program error
 08h (8)  not found
 09h (9)  bad format
 0Ah (10) locked
 0Bh (11) media error
 0Ch (12) already exists / collision with existing item
 0Dh (13) unknown / other
 0Eh (14) (undoc) cannot
 0Fh (15) (undoc) time
@end example

Values for suggested action (@var{action} field):
@example
 01h   retry
 02h   delayed retry (after pause)
 03h   prompt user to reenter input
 04h   abort after cleanup
 05h   immediate abort ("panic")
 06h   ignore
 07h   retry after user intervention
@end example

Values for error locus (@var{locus} field):
@example
 01h   unknown or not appropriate
 02h   block device (disk error)
 03h   network related
 04h   serial device (timeout)
 04h   (PTS-DOS 6.51+ & S/DOS 1.0+) character device
 05h   memory related
@end example

@subheading Return Value

Returns with the extended error code.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

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

int main(void)
@{
  FILE *fp;
  struct DOSERROR de;

  fp = fopen("EXAMPLE.DAT","r");
  if ( fp == NULL )
  @{
    puts("Unable to open file for reading.");
    dosexterr(&de);
    printf("Extended DOS error information:\n");
    printf("Extended error: %i\n",de.exterror);
    printf("Class:          %x\n",de.class);
    printf("Action:         %x\n",de.action);
    printf("Error Locus:    %x\n",de.locus);
  @}
  return 0;
@}
@end example

@c -----------------------------------------------------------------------------
@node dosmemget, dosmemgetb, dosexterr, Alphabetical List
@unnumberedsec dosmemget
@c From file ./pc_hw/mem/dmg.txh
@findex dosmemget
@subheading Syntax

@example
#include <sys/movedata.h>

void dosmemget(int offset, int length, void *buffer);
@end example

@subheading Description

This function transfers data from MS-DOS's conventional memory space to
the program's virtual address space.  The @var{offset} is a physical
address, which can be computed from a real-mode segment/offset pair as
follows:

@example
offset = segment * 16 + offset;
@end example

The @var{length} is the number of bytes to transfer, and @var{buffer} is
a pointer to somewhere in your virtual address space (such as memory
obtained from @code{malloc}) where the data will go.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
unsigned short shift_state;
dosmemget(0x417, 2, &shift_state);
if (shift_state & 0x0004)
  /* Ctrl key pressed */;
@end example

@c -----------------------------------------------------------------------------
@node dosmemgetb, dosmemgetl, dosmemget, Alphabetical List
@unnumberedsec dosmemgetb
@c From file ./pc_hw/mem/dmgb.txh
@findex _dosmemgetb
@subheading Syntax

@example
#include <sys/movedata.h>

void _dosmemgetb(unsigned long offset, size_t xfers, void *buffer);
@end example

@subheading Description

This function transfers data from MS-DOS's conventional memory space
to the program's virtual address space, using only byte transfers.
The @var{offset} is a physical address, which can be computed from a
real-mode segment/offset pair as follows:

@example
offset = segment * 16 + offset;
@end example

The @var{xfers} is the number of bytes to transfer, and @var{buffer} is
a pointer to somewhere in your virtual address space (such as memory
obtained from @code{malloc}) where the data will go.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
unsigned short shift_state;
_dosmemgetb(0x417, 2, &shift_state);
if (shift_state & 0x0004)
  /* Ctrl key pressed */;
@end example

@c -----------------------------------------------------------------------------
@node dosmemgetl, dosmemgetw, dosmemgetb, Alphabetical List
@unnumberedsec dosmemgetl
@c From file ./pc_hw/mem/dmgl.txh
@findex _dosmemgetl
@subheading Syntax

@example
#include <sys/movedata.h>

void _dosmemgetl(unsigned long offset, size_t xfers, void *buffer);
@end example

@subheading Description

This function transfers data from MS-DOS's conventional memory space
to the program's virtual address space, using only long-word (32-bit)
transfers.  The @var{offset} is a physical address, which can be
computed from a real-mode segment/offset pair as follows:

@example
offset = segment * 16 + offset;
@end example

The @var{count} is the number of long-words to transfer, and
@var{buffer} is a pointer to somewhere in your virtual address space
(such as memory obtained from @code{malloc}) where the data will go.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
unsigned long shift_state;
_dosmemgetl(0x417, 1, &shift_state);
if (shift_state & 0x0004)
  /* Ctrl key pressed */;
@end example

@c -----------------------------------------------------------------------------
@node dosmemgetw, dosmemput, dosmemgetl, Alphabetical List
@unnumberedsec dosmemgetw
@c From file ./pc_hw/mem/dmgw.txh
@findex _dosmemgetw
@subheading Syntax

@example
#include <sys/movedata.h>

void _dosmemgetw(unsigned long offset, size_t xfers, void *buffer);
@end example

@subheading Description

This function transfers data from MS-DOS's conventional memory space
to the program's virtual address space, using only short-word (16-bit)
transfers.  The @var{offset} is a physical address, which can be
computed from a real-mode segment/offset pair as follows:

@example
offset = segment * 16 + offset;
@end example

The @var{xfers} is the number of words to transfer, and @var{buffer}
is a pointer to somewhere in your virtual address space (such as
memory obtained from @code{malloc}) where the data will go.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
unsigned short shift_state;
_dosmemgetw(0x417, 1, &shift_state);
if (shift_state & 0x0004)
  /* Ctrl key pressed */;
@end example

@c -----------------------------------------------------------------------------
@node dosmemput, dosmemputb, dosmemgetw, Alphabetical List
@unnumberedsec dosmemput
@c From file ./pc_hw/mem/dmp.txh
@findex dosmemput
@subheading Syntax

@example
#include <sys/movedata.h>

void dosmemput(const void *buffer, int length, int offset);
@end example

@subheading Description

This function transfers data from the program's virtual address space to
MS-DOS's conventional memory space.  The @var{offset} is a physical
address, which can be computed from a real-mode segment/offset pair as
follows:

@example
offset = segment * 16 + offset;
@end example

The @var{length} is the number of bytes to transfer, and @var{buffer} is
a pointer to somewhere in your virtual address space (such as memory
obtained from @code{malloc}) where the data will come from. 

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
unsigned short save_screen[25][80];
dosmemput(save_screen, 80*2*25, 0xb8000);
@end example

@c -----------------------------------------------------------------------------
@node dosmemputb, dosmemputl, dosmemput, Alphabetical List
@unnumberedsec dosmemputb
@c From file ./pc_hw/mem/dmpb.txh
@findex _dosmemputb
@subheading Syntax

@example
#include <sys/movedata.h>

void _dosmemputb(const void *buffer, size_t xfers,
                 unsigned long offset);
@end example

@subheading Description

This function transfers data from the program's virtual address space
to MS-DOS's conventional memory space, using only byte (8-bit)
transfers.  The @var{offset} is a physical address, which can be
computed from a real-mode segment/offset pair as follows:

@example
offset = segment * 16 + offset;
@end example

The @var{xfers} is the number of bytes to transfer, and @var{buffer}
is a pointer to somewhere in your virtual address space (such as
memory obtained from @code{malloc}) where the data will come from.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
unsigned short save_screen[25][80];
_dosmemputb(save_screen, 0xb8000, 80*2*25);
@end example

@c -----------------------------------------------------------------------------
@node dosmemputl, dosmemputw, dosmemputb, Alphabetical List
@unnumberedsec dosmemputl
@c From file ./pc_hw/mem/dmpl.txh
@findex _dosmemputl
@subheading Syntax

@example
#include <sys/movedata.h>

void _dosmemputl(const void *buffer, size_t xfers,
                 unsigned long offset);
@end example

@subheading Description

This function transfers data from the program's virtual address space
to MS-DOS's conventional memory space, using only long-word (32-bit)
transfers.  The @var{offset} is a physical address, which can be
computed from a real-mode segment/offset pair as follows:

@example
offset = segment * 16 + offset;
@end example

The @var{xfers} is the number of long-words to transfer, and
@var{buffer} is a pointer to somewhere in your virtual address space
(such as memory obtained from @code{malloc}) where the data will come
from.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
unsigned short save_screen[25][80];
_dosmemputl(save_screen, 40*25, 0xb8000);
@end example

@c -----------------------------------------------------------------------------
@node dosmemputw, dostrerr, dosmemputl, Alphabetical List
@unnumberedsec dosmemputw
@c From file ./pc_hw/mem/dmpw.txh
@findex _dosmemputw
@subheading Syntax

@example
#include <sys/movedata.h>

void _dosmemputw(const void *buffer, size_t xfers,
                 unsigned long offset);
@end example

@subheading Description

This function transfers data from the program's virtual address space
to MS-DOS's conventional memory space, using only short-word (16-bit)
transfers.  The @var{offset} is a physical address, which can be
computed from a real-mode segment/offset pair as follows:

@example
offset = segment * 16 + offset;
@end example

The @var{xfers} is the number of short-words to transfer, and
@var{buffer} is a pointer to somewhere in your virtual address space
(such as memory obtained from @code{malloc}) where the data will come
from.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
unsigned short save_screen[25][80];
_dosmemputw(save_screen, 0xb8000, 80*25);
@end example

@c -----------------------------------------------------------------------------
@node dostrerr, DPMI Overview, dosmemputw, Alphabetical List
@unnumberedsec dostrerr
@c From file ./dos/compat/d_exterr.txh
@findex dostrerr
@tindex DOSERROR_STR@r{ structure}
@subheading Syntax

@example
#include <dos.h>

int dostrerr(struct DOSERROR *p_error, struct DOSERROR_str *p_str);
@end example

@subheading Description

This function accepts the extended error structure from DOS (e.g., from
the returned parameter from function @code{dosexterr},
@pxref{dosexterr}) and returns the strings which describes that error
structure in the structure pointed to by the second parameter.  This
function is a DOS analogue of the ANSI function @code{strerror}
(@pxref{strerror}), and can be used to print descriptive messages
corresponding to the errors described in the @code{DOSERROR} structure.

For a list of the strings returned for each error number and type, see
@ref{dosexterr}.

@var{p_error} must point to the following structure:

@example
struct DOSERROR @{
  int  exterror;
  char class;
  char action;
  char locus;
@};
@end example

@var{p_str} must point to the following structure:

@example
struct DOSERROR_STR @{
  char *exterror_str;
  char *class_str;
  char *action_str;
  char *locus_str;
@};
@end example


@subheading Return Value

If either pointer parameter is @code{NULL}, returns -1 and sets
@code{errno} to EINVAL.  If both parameters are not @code{NULL}, checks
the value of each member of the @code{DOSERROR} parameter @var{p_error}.
If each value is within the limits of valid error codes for that member,
sets parameter @var{p_str} member fields with the corresponding string
describing the error code.  If any error code is outside of the valid
values for that code, sets the corresponding @var{p_str} member to the
string ``Unknown error: '' followed by the decimal numeric value of the
error code.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

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

int main(void)
@{
  FILE *fp;
  struct DOSERROR de;
  struct DOSERROR_STR se;

  fp = fopen("EXAMPLE.DAT","r");
  if ( fp == NULL )
  @{
    puts("Unable to open file for reading.");
    dosexterr(&de);
    dostrerr(&de, &se);
    printf("Extended DOS error information:\n");
    printf("Extended error: %i : %s\n",de.exterror,se.exterror_str);
    printf("Class:          %x : %s\n",de.class,se.class_str);
    printf("Action:         %x : %s\n",de.action,se.action_str);
    printf("Error Locus:    %x : %s\n",de.locus,se.locus_str);
  @}
  return 0;
@}
@end example
@c -----------------------------------------------------------------------------
@node DPMI Overview, DPMI Specification, dostrerr, Alphabetical List
@unnumberedsec DPMI Overview
@c From file ./dpmi/api/dpmi.txh
@vindex __dpmi_error
@tindex __dpmi_raddr@r{ type}
@tindex __dpmi_paddr@r{ type}
@tindex __dpmi_meminfo@r{ type}
@tindex __dpmi_regs@r{ type}
@tindex __dpmi_version_ret@r{ type}
@tindex __dpmi_free_mem_info@r{ type}
@tindex __dpmi_memory_info@r{ type}
@tindex __dpmi_callback_info@r{ type}
@tindex __dpmi_shminfo@r{ type}

@example
extern unsigned short __dpmi_error;
@end example

For most functions, the error returned from the DPMI server is stored
in this variable.

@example
typedef struct @{
  unsigned short offset16;
  unsigned short segment;
@} __dpmi_raddr;
@end example

This structure is used to hold a real-mode address, which consists of
a segment:offset pair.

@example
typedef struct @{
  unsigned long  offset32;
  unsigned short selector;
@} __dpmi_paddr;
@end example

This structure is used to hold a protected-mode address, which consists of
a selector:offset pair.

@example
typedef struct @{
  unsigned long handle;			/* 0, 2 */
  unsigned long size; 	/* or count */	/* 4, 6 */
  unsigned long address;		/* 8, 10 */
@} __dpmi_meminfo;
@end example

This structure is used by many functions that need to refer to blocks
of 32-bit memory.  The @code{size} field doubles as a count for those
operations that want a count of something, or return a count.

@example
typedef union @{
  struct @{
    unsigned long edi;
    unsigned long esi;
    unsigned long ebp;
    unsigned long res;
    unsigned long ebx;
    unsigned long edx;
    unsigned long ecx;
    unsigned long eax;
  @} d;
  struct @{
    unsigned short di, di_hi;
    unsigned short si, si_hi;
    unsigned short bp, bp_hi;
    unsigned short res, res_hi;
    unsigned short bx, bx_hi;
    unsigned short dx, dx_hi;
    unsigned short cx, cx_hi;
    unsigned short ax, ax_hi;
    unsigned short flags;
    unsigned short es;
    unsigned short ds;
    unsigned short fs;
    unsigned short gs;
    unsigned short ip;
    unsigned short cs;
    unsigned short sp;
    unsigned short ss;
  @} x;
  struct @{
    unsigned char edi[4];
    unsigned char esi[4];
    unsigned char ebp[4];
    unsigned char res[4];
    unsigned char bl, bh, ebx_b2, ebx_b3;
    unsigned char dl, dh, edx_b2, edx_b3;
    unsigned char cl, ch, ecx_b2, ecx_b3;
    unsigned char al, ah, eax_b2, eax_b3;
  @} h;
@} __dpmi_regs;
@end example

This structure is used by functions that pass register information,
such as simulating real-mode calls.

@example  
typedef struct @{
  unsigned char  major;
  unsigned char  minor;
  unsigned short flags;
  unsigned char  cpu;
  unsigned char  master_pic;
  unsigned char  slave_pic;
@} __dpmi_version_ret;
@end example

This structure is used to return version information to the program.

@example
typedef struct @{
  unsigned long largest_available_free_block_in_bytes;
  unsigned long maximum_unlocked_page_allocation_in_pages;
  unsigned long maximum_locked_page_allocation_in_pages;
  unsigned long linear_address_space_size_in_pages;
  unsigned long total_number_of_unlocked_pages;
  unsigned long total_number_of_free_pages;
  unsigned long total_number_of_physical_pages;
  unsigned long free_linear_address_space_in_pages;
  unsigned long size_of_paging_file_partition_in_pages;
  unsigned long reserved[3];
@} __dpmi_free_mem_info;
@end example

This structure is used to return information about the state of
virtual memory in the system.

@example
typedef struct @{
  unsigned long total_allocated_bytes_of_physical_memory_host;
  unsigned long total_allocated_bytes_of_virtual_memory_host;
  unsigned long total_available_bytes_of_virtual_memory_host;
  unsigned long total_allocated_bytes_of_virtual_memory_vcpu;
  unsigned long total_available_bytes_of_virtual_memory_vcpu;
  unsigned long total_allocated_bytes_of_virtual_memory_client;
  unsigned long total_available_bytes_of_virtual_memory_client;
  unsigned long total_locked_bytes_of_memory_client;
  unsigned long max_locked_bytes_of_memory_client;
  unsigned long highest_linear_address_available_to_client;
  unsigned long size_in_bytes_of_largest_free_memory_block;
  unsigned long size_of_minimum_allocation_unit_in_bytes;
  unsigned long size_of_allocation_alignment_unit_in_bytes;
  unsigned long reserved[19];
@} __dpmi_memory_info;
@end example

This is also used to return memory information, but by a different
function.

@example
typedef struct @{
  unsigned long data16[2];
  unsigned long code16[2];
  unsigned short ip;
  unsigned short reserved;
  unsigned long data32[2];
  unsigned long code32[2];
  unsigned long eip;
@} __dpmi_callback_info;
@end example

This structure is used to install TSR programs.

@example
typedef struct @{
  unsigned long size_requested;
  unsigned long size;
  unsigned long handle;
  unsigned long address;
  unsigned long name_offset;
  unsigned short name_selector;
  unsigned short reserved1;
  unsigned long reserved2;
@} __dpmi_shminfo;
@end example

This structure is used to manipulate shared memory regions.
@c -----------------------------------------------------------------------------
@node DPMI Specification, __dpmi_allocate_dos_memory, DPMI Overview, Alphabetical List
@unnumberedsec DPMI Specification
@c From file ./dpmi/api/dpmi.txh

To obtain the DPMI specification, Contact Intel and order document
number 240977-001.  Also, try ftp.qdeck.com:/pub/memory/dpmi*
and http://www.delorie.com/djgpp/doc/dpmi/.

@c -----------------------------------------------------------------------------
@node __dpmi_allocate_dos_memory, __dpmi_allocate_ldt_descriptors, DPMI Specification, Alphabetical List
@unnumberedsec __dpmi_allocate_dos_memory
@c From file ./dpmi/api/d0100.txh
@findex __dpmi_allocate_dos_memory
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_allocate_dos_memory(int _paragraphs,
                               int *_ret_selector_or_max);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0100

This function allocates DOS memory.  You pass it the number of
paragraphs ((bytes+15)>>4) to allocate.  If it succeeds, it returns a
segment (dos-style) and fills in @var{_ret_selector_or_max} with a
selector (protected-mode) that you can use to reference the same
memory.  Note that it's the selector you use to free the block, not
the segment.

@subheading Return Value

-1 on error, else the segment [0000..FFFF].

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_allocate_ldt_descriptors, __dpmi_allocate_linear_memory, __dpmi_allocate_dos_memory, Alphabetical List
@unnumberedsec __dpmi_allocate_ldt_descriptors
@c From file ./dpmi/api/d0000.txh
@findex __dpmi_allocate_ldt_descriptors
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_allocate_ldt_descriptors(int count);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0000

Allocates @var{count} descriptors.

@subheading Return Value

-1 on error, else the first descriptor.  Use
@code{__dpmi_get_selector_increment_value}
(@pxref{__dpmi_get_selector_increment_value}) to figure out
the remaining selectors.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
short sel = __dpmi_allocate_ldt_descriptors(1);
@end example

@c -----------------------------------------------------------------------------
@node __dpmi_allocate_linear_memory, __dpmi_allocate_memory, __dpmi_allocate_ldt_descriptors, Alphabetical List
@unnumberedsec __dpmi_allocate_linear_memory
@c From file ./dpmi/api/d0504.txh
@findex __dpmi_allocate_linear_memory
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_allocate_linear_memory(__dpmi_meminfo *info, int commit);
@end smallexample

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0504 (DPMI 1.0 only).  Not supported by CWSDPMI and
Windows.

This allocates a block of page-aligned linear address space.  Pass a
desired address (or zero for any) and a size.  @var{commit} is 1 for
committed pages, else they are uncommitted.  It returns a handle and
the actual address.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_allocate_memory, __dpmi_allocate_real_mode_callback, __dpmi_allocate_linear_memory, Alphabetical List
@unnumberedsec __dpmi_allocate_memory
@c From file ./dpmi/api/d0501.txh
@findex __dpmi_allocate_memory
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_allocate_memory(__dpmi_meminfo *_info);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0501

This allocates virtual memory.  Fill in size, returns handle and address.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_allocate_real_mode_callback, __dpmi_allocate_shared_memory, __dpmi_allocate_memory, Alphabetical List
@unnumberedsec __dpmi_allocate_real_mode_callback
@c From file ./dpmi/api/d0303.txh
@findex __dpmi_allocate_real_mode_callback
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_allocate_real_mode_callback(void (*_handler)(void),
                                       __dpmi_regs *_regs,
                                       __dpmi_raddr *_ret);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0303

This function gives you a real-mode address to pass to TSRs that gets
reflected to your protected-mode handler.  You pass it a register
block to use; it gets filled in with the real-mode registers when your
handler is called, and the registers are set from it when the handler
returns.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_allocate_shared_memory, __dpmi_allocate_specific_ldt_descriptor, __dpmi_allocate_real_mode_callback, Alphabetical List
@unnumberedsec __dpmi_allocate_shared_memory
@c From file ./dpmi/api/d0d00.txh
@findex __dpmi_allocate_shared_memory
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_allocate_shared_memory(__dpmi_shminfo *info);
@end smallexample

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0d00 (DPMI 1.0 only).  Not supported by CWSDPMI and
Windows.

This function allocates a shared memory block that can be accessed from
different virtual machines.  Fill the required length in
@code{@var{info}->size_requested}.  The function fills the rest of the
structure: allocated length in @code{@var{info}->size}, block handle in
@code{@var{info}->handle}, linear address in @code{@var{info}->address},
and the selector:offset of an @sc{asciiz} block name (up to 128 bytes
long) in @code{@var{info}->name_selector} and
@code{@var{info}->name_offset}, respectively.

The access to the shared memory block can be serialized by calling
the @code{__dpmi_serialize_on_shared_memory} function
(@pxref{__dpmi_serialize_on_shared_memory}).

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_allocate_specific_ldt_descriptor, __dpmi_clear_debug_watchpoint, __dpmi_allocate_shared_memory, Alphabetical List
@unnumberedsec __dpmi_allocate_specific_ldt_descriptor
@c From file ./dpmi/api/d000d.txh
@findex __dpmi_allocate_specific_ldt_descriptor
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_allocate_specific_ldt_descriptor(int _selector);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x000d

This allocates the specific selector given.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_clear_debug_watchpoint, __dpmi_create_alias_descriptor, __dpmi_allocate_specific_ldt_descriptor, Alphabetical List
@unnumberedsec __dpmi_clear_debug_watchpoint
@c From file ./dpmi/api/d0b01.txh
@findex __dpmi_clear_debug_watchpoint
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_clear_debug_watchpoint(unsigned long _handle);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0b01

Clear a debug watchpoint.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_create_alias_descriptor, __dpmi_discard_page_contents, __dpmi_clear_debug_watchpoint, Alphabetical List
@unnumberedsec __dpmi_create_alias_descriptor
@c From file ./dpmi/api/d000a.txh
@findex __dpmi_create_alias_descriptor
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_create_alias_descriptor(int _selector);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x000a

Create a new selector with the same parameters as the given one.

@subheading Return Value

-1 on error, else the new selector.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_discard_page_contents, __dpmi_free_dos_memory, __dpmi_create_alias_descriptor, Alphabetical List
@unnumberedsec __dpmi_discard_page_contents
@c From file ./dpmi/api/d0703.txh
@findex __dpmi_discard_page_contents
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_discard_page_contents(__dpmi_meminfo *_info);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0703

Advises the server that the given pages are no longer needed and may
be reclaimed.  Fill in address and size (in bytes).

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_free_dos_memory, __dpmi_free_ldt_descriptor, __dpmi_discard_page_contents, Alphabetical List
@unnumberedsec __dpmi_free_dos_memory
@c From file ./dpmi/api/d0101.txh
@findex __dpmi_free_dos_memory
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_free_dos_memory(int _selector);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0101

This function frees the dos memory allocated by
@ref{__dpmi_allocate_dos_memory}.  Remember to pass the selector and
not the segment.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_free_ldt_descriptor, __dpmi_free_memory, __dpmi_free_dos_memory, Alphabetical List
@unnumberedsec __dpmi_free_ldt_descriptor
@c From file ./dpmi/api/d0001.txh
@findex __dpmi_free_ldt_descriptor
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_free_ldt_descriptor(int descriptor);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0001

This function frees a single descriptor, even if it was allocated as
one of many.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
__dpmi_free_ldt_descriptor(sel);
@end example

@c -----------------------------------------------------------------------------
@node __dpmi_free_memory, __dpmi_free_physical_address_mapping, __dpmi_free_ldt_descriptor, Alphabetical List
@unnumberedsec __dpmi_free_memory
@c From file ./dpmi/api/d0502.txh
@findex __dpmi_free_memory
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_free_memory(unsigned long _handle);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0502

This frees a block of virtual memory.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_free_physical_address_mapping, __dpmi_free_real_mode_callback, __dpmi_free_memory, Alphabetical List
@unnumberedsec __dpmi_free_physical_address_mapping
@c From file ./dpmi/api/d0801.txh
@findex __dpmi_free_physical_address_mapping
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_free_physical_address_mapping(__dpmi_meminfo *info);
@end smallexample

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0801 (DPMI 1.0 only).  Not supported by CWSDPMI and
Windows.

This function unmaps a physical device mapped with
@ref{__dpmi_physical_address_mapping}.  Fill in the linear address.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_free_real_mode_callback, __dpmi_free_serialization_on_shared_memory, __dpmi_free_physical_address_mapping, Alphabetical List
@unnumberedsec __dpmi_free_real_mode_callback
@c From file ./dpmi/api/d0304.txh
@findex __dpmi_free_real_mode_callback
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_free_real_mode_callback(__dpmi_raddr *_addr);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0303

This function frees the real-mode callback address.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_free_serialization_on_shared_memory, __dpmi_free_shared_memory, __dpmi_free_real_mode_callback, Alphabetical List
@unnumberedsec __dpmi_free_serialization_on_shared_memory
@c From file ./dpmi/api/d0d03.txh
@findex __dpmi_free_serialization_on_shared_memory
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_free_serialization_on_shared_memory(unsigned long handle, 
                                               int flags);
@end smallexample

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0d03 (DPMI 1.0 only).  Not supported by CWSDPMI and
Windows.

This function frees the serialization on shared memory block specified
by its handle @var{handle}.  The bit-mapped variable @var{flags} defines
the following bits:

@table @asis
@item bit 0
If set, release shared serialization (as opposed to exclusive
serialization).

@item bit 1
If set, free pending serialization.

@item bits 2-15
Reserved (should be zero).
@end table


@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_free_shared_memory, __dpmi_get_and_disable_virtual_interrupt_state, __dpmi_free_serialization_on_shared_memory, Alphabetical List
@unnumberedsec __dpmi_free_shared_memory
@c From file ./dpmi/api/d0d01.txh
@findex __dpmi_free_shared_memory
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_free_shared_memory(unsigned long handle);
@end smallexample

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0d01 (DPMI 1.0 only).  Not supported by CWSDPMI and
Windows.

This function frees the shared memory block specified by the given
@var{handle}.  The handle becomes invalid after this call.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_and_disable_virtual_interrupt_state, __dpmi_get_and_enable_virtual_interrupt_state, __dpmi_free_shared_memory, Alphabetical List
@unnumberedsec __dpmi_get_and_disable_virtual_interrupt_state
@c From file ./dpmi/api/d0900.txh
@findex __dpmi_get_and_disable_virtual_interrupt_state
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_get_and_disable_virtual_interrupt_state(void);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0900

This function disables interrupts, and returns the previous setting.

@subheading Return Value

The previous setting.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_and_enable_virtual_interrupt_state, __dpmi_get_and_set_virtual_interrupt_state, __dpmi_get_and_disable_virtual_interrupt_state, Alphabetical List
@unnumberedsec __dpmi_get_and_enable_virtual_interrupt_state
@c From file ./dpmi/api/d0901.txh
@findex __dpmi_get_and_enable_virtual_interrupt_state
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_get_and_enable_virtual_interrupt_state(void);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0901

This function enables interrupts, and returns the previous setting.

@subheading Return Value

The previous setting.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_and_set_virtual_interrupt_state, __dpmi_get_capabilities, __dpmi_get_and_enable_virtual_interrupt_state, Alphabetical List
@unnumberedsec __dpmi_get_and_set_virtual_interrupt_state
@c From file ./dpmi/api/d09.txh
@findex __dpmi_get_and_set_virtual_interrupt_state
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_get_and_set_virtual_interrupt_state(int _old_state);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AH = 0x09

This function restores the interrupt state from a previous call to
@code{__dpmi_get_and_disable_virtual_interrupt_state}
(@pxref{__dpmi_get_and_disable_virtual_interrupt_state}) or
@code{__dpmi_get_and_enable_virtual_interrupt_state}
(@pxref{__dpmi_get_and_enable_virtual_interrupt_state}).

@subheading Return Value

The previous setting.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_capabilities, __dpmi_get_coprocessor_status, __dpmi_get_and_set_virtual_interrupt_state, Alphabetical List
@unnumberedsec __dpmi_get_capabilities
@c From file ./dpmi/api/d0401.txh
@findex __dpmi_get_capabilities
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_get_capabilities(int *flags, char *vendor_info);
@end smallexample

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0401 (DPMI 1.0 only).  Not supported by CWSDPMI and
Windows.

Gets the capabilities of the server.  @var{flags} are as follows:

@example
---- ---X = 1="page accessed/dirty" supported
---- --X- = 1="exceptions restartable" supported
---- -X-- = 1="device mapping" supported
---- X--- = 1="map conventional memory" supported
---X ---- = 1="demand zero-fill" supported
--X- ---- = 1="write-protect client" supported
-X-- ---- = 1="write-protect host" supported
@end example

The vendor info is a 128-byte buffer:

@example
[0] host major number
[1] host minor number
[2..127] vendor name
@end example

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_coprocessor_status, __dpmi_get_descriptor, __dpmi_get_capabilities, Alphabetical List
@unnumberedsec __dpmi_get_coprocessor_status
@c From file ./dpmi/api/d0e00.txh
@findex __dpmi_get_coprocessor_status
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_get_coprocessor_status(void);
@end smallexample

@subheading Description

Please refer to @ref{DPMI Specification}, for details on DPMI
function call operation.  Also see @ref{DPMI Overview}, for general
information.

DPMI function AX = 0x0e00 (DPMI 1.0 only).  Not supported by CWSDPMI and
Windows.

@subheading Return Value

-1 on error, else returns the processor status flags.  Here's the
meaning of each set bit:

@table @asis
@item bit 0
If set, co-processor is enabled.  If reset, co-processor is disabled.

@item bit 1
If set, the application is emulating the co-processor.

@item bit 2
If set, the numeric co-processor is present.

@item bit 3
If set, the DPMI host is emulating the co-processor.

@item bits 4-7
The co-processor type:

@table @code
@item 0000
none
@item 0010
80287
@item 0011
80387
@item 0100
80486 with a numeric processor
@end table

@end table


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_descriptor, __dpmi_get_descriptor_access_rights, __dpmi_get_coprocessor_status, Alphabetical List
@unnumberedsec __dpmi_get_descriptor
@c From file ./dpmi/api/d000b.txh
@findex __dpmi_get_descriptor
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_get_descriptor(int _selector, void *_buffer);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x000b

This function fills the 8-byte buffer pointed to by @var{_buffer} with
the parameters of the descriptor whose selector is passed in
@var{_selector}.  The data has the following format:

@example
[0] XXXX XXXX = segment limit [7:0]
[1] XXXX XXXX = segment limit [15:8]
[2] XXXX XXXX = base address [7:0]
[3] XXXX XXXX = base address [15:8]
[4] XXXX XXXX = base address [23:16]
[5] ---- XXXX = type; see details below
[5] ---X ---- = 0=system, 1=application (must be 1)
[5] -XX- ---- = privilege level, usually 3 (binary 11)
[5] X--- ---- = 0=absent, 1=present; usually 1
[6] ---- XXXX = segment limit [19:16]
[6] ---X ---- = available for user; see details below
[6] --0- ---- = must be zero
[6] -X-- ---- = 0=16-bit 1=32-bit; usually 1
[6] X--- ---- = 0=byte-granular (small) 1=page-granular (big)
[7] XXXX XXXX = base address [31:24]
@end example

Here's an alternative view of the layout that treats the buffer as an
array of 4 16-bit words (i.e., @code{unsigned short}s):

@example
[0] XXXX XXXX XXXX XXXX = segment limit [15:0]
[1] XXXX XXXX XXXX XXXX = base address  [15:0]
[2] ---- ---- XXXX XXXX = base address [23:16]
[2] ---- XXXX ---- ---- = type; see details below
[2] ---1 ---- ---- ---- = 0=system, 1=application; must be 1
[2] -XX- ---- ---- ---- = privilege level, usually 3 (binary 11)
[2] X--- ---- ---- ---- = 0=absent, 1=present; usually 1
[3] ---- ---- ---- XXXX = segment limit [19:16]
[3] ---- ---- ---X ---- = available for user; see details below
[3] ---- ---- --0- ---- = must be zero
[3] ---- ---- -X-- ---- = 0=16-bit 1=32-bit; usually 1
[3] ---- ---- X--- ---- = 0=byte-granular (small) 1=page-granular (big)
[3] XXXX XXXX ---- ---- = base address [31:24]
@end example

Special considerations apply to some of the fields:

@table @asis
@item Segment Limit fields

The segment limit is specified as a 20-bit number.  This number is
interpreted as a number of bytes if the granularity bit (bit 7 of byte
6) is not set, and as a number of 4KB pages if the granularity bit is
set.  Offsets larger than the limit will generate a @dfn{GPF}, the
General Protection Fault exception.

For expand-down data segments (see below), the segment limit is the
@emph{lower} limit of the segment; the upper limit is either 0xffffffff
or 0xffff, depending on whether the size bit is set (32-bit default
size) or not (16-bit default size).  For expand-down segments, values of
offset @emph{less} than the segment limit result in a GPF.

@item Base Address fields

Segment base address should generally be 16-byte aligned.  This is not
required, but it maximizes performance by aligning code and data on
16-byte boundaries.

@item Type field

This field has different meanings depending on whether the descriptor is
for code or data segment.  For code segments, the meaning is as follows:

@example
---X = 0=not accessed, 1=accessed
--1- = 0=execute only, 1=execute/read; must be 1
-0-- = 0=non-conforming, 1=conforming; must be 0
1--- = 0=data segment, 1=code segment
@end example

The accessed/not accessed bit indicates whether the segment has been
accessed since the last time the bit was cleared.  This bit is set
whenever the segment selector is loaded into a segment register, and the
bit then remains set until explicitly cleared.  This bit can be used for
debugging purposes.

The read bit must be set to allow reading data from the code segment,
which is done in several cases by the library.  The DPMI spec
(@pxref{DPMI Specification}) requires this bit to be 1 for code
segments.

The conforming bit must be cleared so that transfer of execution into
this segment from a less-privileged segment will result in a GPF.  The
DPMI spec (@pxref{DPMI Specification}) requires this bit to be 0 for
code segments.

For data segments, the meaning of the @code{type} field is as follows:

@example
---X = 0=not accessed, 1=accessed
--X- = 0=read-only, 1=read/write
-X-- = 0=expand-up, 1=expand-down; usually 0
0--- = 0=data segment, 1=code segment
@end example

The accessed/not accessed bit has the same meaning as for code segments.
The expand up/down bit is meant to be 1 for stack segments whose size
should be changed dynamically, whereby changing the limit adds the
additional space to the bottom of the stack; for data segments and
statically-sized stack segments, this bit is usually zero.

@item Present bit

If this bit is clear, a segment-not-present exception will be generated
when the selector is loaded into a segment register, and all the fields
of the descriptor except the privilege level and the system/application
bit are available for CPU/OS to store their own data.  Don't clear this
bit unless you know what you are doing.

@item Available bit

This bit is left for the application's use.  It is neither set nor
cleared by the DPMI server.
@end table

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_descriptor_access_rights, __dpmi_get_extended_exception_handler_vector_pm, __dpmi_get_descriptor, Alphabetical List
@unnumberedsec __dpmi_get_descriptor_access_rights
@c From file ./dpmi/api/dpmi_lar.txh
@findex __dpmi_get_descriptor_access_rights
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_get_descriptor_access_rights(int _selector);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

This function returns the access rights byte from the @code{lar}
opcode.

@subheading Return Value

The access byte.  @xref{__dpmi_set_descriptor_access_rights}, for the
details about the access information returned.  Also see
@ref{__dpmi_get_descriptor}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_extended_exception_handler_vector_pm, __dpmi_get_extended_exception_handler_vector_rm, __dpmi_get_descriptor_access_rights, Alphabetical List
@unnumberedsec __dpmi_get_extended_exception_handler_vector_pm
@c From file ./dpmi/api/d0210.txh
@findex __dpmi_get_extended_exception_handler_vector_pm
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_get_extended_exception_handler_vector_pm(
        int vector, __dpmi_paddr *address
);
@end smallexample

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0210 (DPMI 1.0 only).  Not supported by CWSDPMI and
Windows.

This gets the function that handles protected mode exceptions.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_extended_exception_handler_vector_rm, __dpmi_get_free_memory_information, __dpmi_get_extended_exception_handler_vector_pm, Alphabetical List
@unnumberedsec __dpmi_get_extended_exception_handler_vector_rm
@c From file ./dpmi/api/d0211.txh
@findex __dpmi_get_extended_exception_handler_vector_rm
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_get_extended_exception_handler_vector_rm(
        int vector, __dpmi_paddr *address
);
@end smallexample

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0211 (DPMI 1.0 only).  Not supported by CWSDPMI and
Windows.

This function gets the handler for real-mode exceptions.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_free_memory_information, __dpmi_get_memory_block_size_and_base, __dpmi_get_extended_exception_handler_vector_rm, Alphabetical List
@unnumberedsec __dpmi_get_free_memory_information
@c From file ./dpmi/api/d0500.txh
@findex __dpmi_get_free_memory_information
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_get_free_memory_information(__dpmi_free_mem_info *_info);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0500

This function returns information about available memory.  Unsupported
fields will have -1 (0xfffffff) in them.

@subheading Return Value

Zero.  This always works.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_memory_block_size_and_base, __dpmi_get_memory_information, __dpmi_get_free_memory_information, Alphabetical List
@unnumberedsec __dpmi_get_memory_block_size_and_base
@c From file ./dpmi/api/d050a.txh
@findex __dpmi_get_memory_block_size_and_base
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_get_memory_block_size_and_base(__dpmi_meminfo *info);
@end smallexample

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x050a (DPMI 1.0 only).  Not supported by CWSDPMI and
Windows.

Pass the handle.  It fills in the address and size.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_memory_information, __dpmi_get_multiple_descriptors, __dpmi_get_memory_block_size_and_base, Alphabetical List
@unnumberedsec __dpmi_get_memory_information
@c From file ./dpmi/api/d050b.txh
@findex __dpmi_get_memory_information
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_get_memory_information(__dpmi_memory_info *buffer);
@end smallexample

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x050b (DPMI 1.0 only).  Not supported by CWSDPMI and
Windows.

This function returns virtual memory information, as follows:

@table @code
@item total_allocated_bytes_of_physical_memory_host
The total amount of allocated physical memory controlled by the DPMI
host.

@item total_allocated_bytes_of_virtual_memory_host
The total amount of allocated virtual memory controlled by the DPMI
host.

@item total_available_bytes_of_virtual_memory_host
The total amount of available virtual memory controlled by the DPMI
host.

@item total_allocated_bytes_of_virtual_memory_vcpu
The amount of virtual memory allocated by the DPMI host for the current
virtual machine.

@item total_available_bytes_of_virtual_memory_vcpu
The amount of virtual memory available for the current virtual machine.

@item total_allocated_bytes_of_virtual_memory_client
The amount of virtual memory allocated by the DPMI host for the current
client (that is, for the calling program).

@item total_available_bytes_of_virtual_memory_client
The amount of virtual memory available to the current client.

@item total_locked_bytes_of_memory_client
The amount of memory locked by the calling program.

@item max_locked_bytes_of_memory_client
Maximum locked memory for the current client.

@item highest_linear_address_available_to_client
The highest linear address available to the calling program.

@item size_in_bytes_of_largest_free_memory_block
Size of the largest available memory block.

@item size_of_minimum_allocation_unit_in_bytes
Size of the smallest block that can be allocated.

@item size_of_allocation_alignment_unit_in_bytes
The alignment of allocated memory blocks.
@end table

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_multiple_descriptors, __dpmi_get_page_attributes, __dpmi_get_memory_information, Alphabetical List
@unnumberedsec __dpmi_get_multiple_descriptors
@c From file ./dpmi/api/d000e.txh
@findex __dpmi_get_multiple_descriptors
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_get_multiple_descriptors(int count, void *buffer);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x000e (DPMI 1.0 only).  Not supported by CWSDPMI and
Windows.

This function gets a list of selectors' parameters.  The buffer pointed
to by @var{buffer} must be prefilled with selector values, and will
contain the parameters on return:

@example
[0x00:2] selector #1 (pass)
[0x02:8] parameters #1 (returned)
[0x0a:2] selector #2 (pass)
[0x0c:8] parameters #2 (returned)
...
@end example

@subheading Return Value

Returns @var{count} if successful, the negative of the number of
descriptors copied if failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_page_attributes, __dpmi_get_page_size, __dpmi_get_multiple_descriptors, Alphabetical List
@unnumberedsec __dpmi_get_page_attributes
@c From file ./dpmi/api/d0506.txh
@findex __dpmi_get_page_attributes
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_get_page_attributes(__dpmi_meminfo *info, short *buffer);
@end smallexample

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0506 (DPMI 1.0 only).  Supported by CWSDPMI, but
not by Windows.

This function retrieves the attributes of a number of pages.  Pass the
handle in @code{@var{info}->handle}, offset of first page (relative to
start of block) in @code{@var{info}->address}, and number of pages in
@code{@var{info}->count}.  The buffer @var{buffer} gets filled in with
the attributes.  For each page, a 16-bit attribute word in @var{buffer}
defines the attributes of that page as follows:

@table @asis
@item bits 0-2
Page type:

@table @code
@item 000
uncommitted
@item 001
committed
@item 010
mapped
@end table

@item bit 3
If set, the page is read/write.  If cleared, the page is read-only.

@item bit 4
If set, bits 5 and 6 specify accessed and dirty bits.

@item bit 5
The page has been accessed (only valid if bit 4 is set).

@item bit 6
The page has been written (is @dfn{dirty}).  Only valid if bit 4 is
set.
@end table

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_page_size, __dpmi_get_processor_exception_handler_vector, __dpmi_get_page_attributes, Alphabetical List
@unnumberedsec __dpmi_get_page_size
@c From file ./dpmi/api/d0604.txh
@findex __dpmi_get_page_size
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_get_page_size(unsigned long *_size);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0604

Fills in the page size.

@subheading Return Value

-1 on error (16-bit host), else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_processor_exception_handler_vector, __dpmi_get_protected_mode_interrupt_vector, __dpmi_get_page_size, Alphabetical List
@unnumberedsec __dpmi_get_processor_exception_handler_vector
@c From file ./dpmi/api/d0202.txh
@findex __dpmi_get_processor_exception_handler_vector
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_get_processor_exception_handler_vector(
        int _vector, __dpmi_paddr *_address
);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0202

This function gets the current protected-mode exception handler (not
interrupts) for the exception @var{_vector}.  It will return a
selector:offset pair in the members of the @var{_address} variable.

@subheading Return Value

-1 on error (invalid vector), else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_protected_mode_interrupt_vector, __dpmi_get_raw_mode_switch_addr, __dpmi_get_processor_exception_handler_vector, Alphabetical List
@unnumberedsec __dpmi_get_protected_mode_interrupt_vector
@c From file ./dpmi/api/d0204.txh
@findex __dpmi_get_protected_mode_interrupt_vector
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_get_protected_mode_interrupt_vector(int _vector,
                                               __dpmi_paddr *_address);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0204

This function gets the address of the current protected mode interrupt
(not exception) handler.  It returns a selector:offset pair.

@subheading Return Value

Zero.  This always works.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_raw_mode_switch_addr, __dpmi_get_real_mode_interrupt_vector, __dpmi_get_protected_mode_interrupt_vector, Alphabetical List
@unnumberedsec __dpmi_get_raw_mode_switch_addr
@c From file ./dpmi/api/d0306.txh
@findex __dpmi_get_raw_mode_switch_addr
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_get_raw_mode_switch_addr(__dpmi_raddr *_rm,
                                    __dpmi_paddr *_pm);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0306

Read the spec for more info.

@subheading Return Value

Zero.  This always works.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_real_mode_interrupt_vector, __dpmi_get_segment_base_address, __dpmi_get_raw_mode_switch_addr, Alphabetical List
@unnumberedsec __dpmi_get_real_mode_interrupt_vector
@c From file ./dpmi/api/d0200.txh
@findex __dpmi_get_real_mode_interrupt_vector
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_get_real_mode_interrupt_vector(int _vector,
                                          __dpmi_raddr *_address);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0200

This function stores the real-mode interrupt vector address in
@var{_address}. This is the same as the DOS get vector call, and
returns a real-mode segment:offset pair.

Bits [31:8] in the vector number are silently ignored.

@subheading Return Value

Zero.  This function always works.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_segment_base_address, __dpmi_get_segment_limit, __dpmi_get_real_mode_interrupt_vector, Alphabetical List
@unnumberedsec __dpmi_get_segment_base_address
@c From file ./dpmi/api/d0006.txh
@findex __dpmi_get_segment_base_address
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_get_segment_base_address(int _selector,
                                    unsigned long *_addr);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0006

The physical base address of the selector is stored in @var{*addr}.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
unsigned long addr;
if (__dpmi_get_segment_base_address(selector, &addr))
  ...
@end example

@c -----------------------------------------------------------------------------
@node __dpmi_get_segment_limit, __dpmi_get_selector_increment_value, __dpmi_get_segment_base_address, Alphabetical List
@unnumberedsec __dpmi_get_segment_limit
@c From file ./dpmi/api/dpmi_lsl.txh
@findex __dpmi_get_segment_limit
@subheading Syntax

@example
#include <dpmi.h>

unsigned __dpmi_get_segment_limit(int _selector);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

@subheading Return Value

The limit of the segment, as returned by the @code{lsl} opcode.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_selector_increment_value, __dpmi_get_state_of_debug_watchpoint, __dpmi_get_segment_limit, Alphabetical List
@unnumberedsec __dpmi_get_selector_increment_value
@c From file ./dpmi/api/d0003.txh
@findex __dpmi_get_selector_increment_value
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_get_selector_increment_value(void);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0003

@subheading Return Value

The value to add to each selector allocated by
__dpmi_allocate_ldt_descriptors to get the next one.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_state_of_debug_watchpoint, __dpmi_get_state_save_restore_addr, __dpmi_get_selector_increment_value, Alphabetical List
@unnumberedsec __dpmi_get_state_of_debug_watchpoint
@c From file ./dpmi/api/d0b02.txh
@findex __dpmi_get_state_of_debug_watchpoint
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_get_state_of_debug_watchpoint(unsigned long _handle,
                                         int *_status);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0b02

Gets the state of the watchpoint.  Pass handle, fills in status (0=not
encountered, 1=encountered).

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_state_save_restore_addr, __dpmi_get_vendor_specific_api_entry_point, __dpmi_get_state_of_debug_watchpoint, Alphabetical List
@unnumberedsec __dpmi_get_state_save_restore_addr
@c From file ./dpmi/api/d0305.txh
@findex __dpmi_get_state_save_restore_addr
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_get_state_save_restore_addr(__dpmi_raddr *_rm,
                                       __dpmi_paddr *_pm);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0305

Read the spec for info.

@subheading Return Value

The number of bytes required to save state.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_vendor_specific_api_entry_point, __dpmi_get_version, __dpmi_get_state_save_restore_addr, Alphabetical List
@unnumberedsec __dpmi_get_vendor_specific_api_entry_point
@c From file ./dpmi/api/d0a00.txh
@findex __dpmi_get_vendor_specific_api_entry_point
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_get_vendor_specific_api_entry_point(char *_id,
                                               __dpmi_paddr *_api);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0a00

Look up a vendor-specific function, given the @emph{name} of the
function.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_version, __dpmi_get_virtual_interrupt_state, __dpmi_get_vendor_specific_api_entry_point, Alphabetical List
@unnumberedsec __dpmi_get_version
@c From file ./dpmi/api/d0400.txh
@findex __dpmi_get_version
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_get_version(__dpmi_version_ret *_ret);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0400

Fills in version information.  The flags are as follows:

@example
---- ---X = 0=16-bit host  1=32-bit host
---- --X- = 0=V86 used for reflected ints, 1=real mode
---- -X-- = 0=no virtual memory, 1=virtual memory supported
@end example

The cpu is 2=80286, 3=80386, 4=80486, etc.

DPMI 0.9 returns major=0 and minor=0x5a.

@subheading Return Value

Zero.  This always works.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_get_virtual_interrupt_state, __dpmi_install_resident_service_provider_callback, __dpmi_get_version, Alphabetical List
@unnumberedsec __dpmi_get_virtual_interrupt_state
@c From file ./dpmi/api/d0902.txh
@findex __dpmi_get_virtual_interrupt_state
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_get_virtual_interrupt_state(void);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0902

@subheading Return Value

This function returns the current interrupt flag (1=enabled).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_install_resident_service_provider_callback, __dpmi_int, __dpmi_get_virtual_interrupt_state, Alphabetical List
@unnumberedsec __dpmi_install_resident_service_provider_callback
@c From file ./dpmi/api/d0c00.txh
@findex __dpmi_install_resident_service_provider_callback
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_install_resident_service_provider_callback(
        __dpmi_callback_info *info
);
@end smallexample

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0c00 (DPMI 1.0 only).  Not supported by CWSDPMI and
Windows.

This function installs a resident service provider callback and declares
an intent to provide resident protected-mode services after terminating
with a call to @code{__dpmi_terminate_and_stay_resident}
(@pxref{__dpmi_terminate_and_stay_resident}).

The various members of @var{info} should be filled as follows:

@table @code
@item data16
An 8-byte descriptor for the 16-bit data segment.

@item code16
An 8-byte descriptor for the 16-bit code segment (zeros if not
supported).

@item ip
A 16-bit offset of the 16-bit callback procedure.

@item data32
An 8-byte descriptor for 32-bit data segment.

@item code32
An 8-byte descriptor for 32-bit code segment (zeros if not supported).

@item eip
A 32-bit offset of the 32-bit callback procedure.
@end table

@xref{__dpmi_get_descriptor}, for the details about the layout of the
8-byte segment descriptor.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_int, __dpmi_lock_linear_region, __dpmi_install_resident_service_provider_callback, Alphabetical List
@unnumberedsec __dpmi_int
@c From file ./dpmi/api/d0300_z.txh
@findex __dpmi_int
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_int(int _vector, __dpmi_regs *_regs);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0300

This function performs a software interrupt in real mode after filling
in @emph{most} the registers from the given structure.  %ss, %esp, and
%eflags are automatically taken care of, unlike
@ref{__dpmi_simulate_real_mode_interrupt}.

The following variables can be used to tune this function.  By
default, these variables are all zero.

@table @code

@item __dpmi_int_ss
@itemx __dpmi_int_sp
@itemx __dpmi_int_flags

These hold the values stored in the appropriate field in the
@code{__dpmi_regs} structure.

@end table

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_lock_linear_region, __dpmi_map_conventional_memory_in_memory_block, __dpmi_int, Alphabetical List
@unnumberedsec __dpmi_lock_linear_region
@c From file ./dpmi/api/d0600.txh
@findex __dpmi_lock_linear_region
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_lock_linear_region(__dpmi_meminfo *_info);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0600

This function locks virtual memory, to prevent page faults during
hardware interrupts.  Pass address and size (in bytes).

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_map_conventional_memory_in_memory_block, __dpmi_map_device_in_memory_block, __dpmi_lock_linear_region, Alphabetical List
@unnumberedsec __dpmi_map_conventional_memory_in_memory_block
@c From file ./dpmi/api/d0509.txh
@findex __dpmi_map_conventional_memory_in_memory_block
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_map_conventional_memory_in_memory_block(
        __dpmi_meminfo *info, unsigned long physaddr
);
@end smallexample

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0509 (DPMI 1.0 only).  Supported by CWSDPMI, but
not by Windows.

This function maps conventional memory (even when virtualized) to
virtual memory.  Pass the handle, offset, and number of pages.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_map_device_in_memory_block, __dpmi_mark_page_as_demand_paging_candidate, __dpmi_map_conventional_memory_in_memory_block, Alphabetical List
@unnumberedsec __dpmi_map_device_in_memory_block
@c From file ./dpmi/api/d0508.txh
@findex __dpmi_map_device_in_memory_block
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_map_device_in_memory_block(__dpmi_meminfo *info, 
                                      unsigned long *physaddr);
@end smallexample

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0508 (DPMI 1.0 only).  Supported by CWSDPMI, but
not by Windows.

This function maps a physical address range to virtual memory.  Pass
the handle, offset relative to the start of the block, and number of
pages to map.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_mark_page_as_demand_paging_candidate, __dpmi_mark_real_mode_region_as_pageable, __dpmi_map_device_in_memory_block, Alphabetical List
@unnumberedsec __dpmi_mark_page_as_demand_paging_candidate
@c From file ./dpmi/api/d0702.txh
@findex __dpmi_mark_page_as_demand_paging_candidate
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_mark_page_as_demand_paging_candidate(__dpmi_meminfo *_info);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0702

Advises the server that certain pages are unlikely to be used soon.
Set address and size (in bytes).

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_mark_real_mode_region_as_pageable, __dpmi_physical_address_mapping, __dpmi_mark_page_as_demand_paging_candidate, Alphabetical List
@unnumberedsec __dpmi_mark_real_mode_region_as_pageable
@c From file ./dpmi/api/d0602.txh
@findex __dpmi_mark_real_mode_region_as_pageable
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_mark_real_mode_region_as_pageable(__dpmi_meminfo *_info);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0602

This function advises the host that the given pages are suitable for
page-out.  Pass address and size (in bytes).

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_physical_address_mapping, __dpmi_relock_real_mode_region, __dpmi_mark_real_mode_region_as_pageable, Alphabetical List
@unnumberedsec __dpmi_physical_address_mapping
@c From file ./dpmi/api/d0800.txh
@findex __dpmi_physical_address_mapping
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_physical_address_mapping(__dpmi_meminfo *_info);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0800

Maps a physical device (like a graphics buffer) to linear memory.
Fill in the physical address and size (in bytes).  On return, the
address is the linear address to use.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_relock_real_mode_region, __dpmi_reset_debug_watchpoint, __dpmi_physical_address_mapping, Alphabetical List
@unnumberedsec __dpmi_relock_real_mode_region
@c From file ./dpmi/api/d0603.txh
@findex __dpmi_relock_real_mode_region
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_relock_real_mode_region(__dpmi_meminfo *_info);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0603

This function relocks the pages unlocked with
@ref{__dpmi_mark_real_mode_region_as_pageable}.  Pass address and
size (in bytes).

@subheading Return Value

-1 on error, else zero.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_reset_debug_watchpoint, __dpmi_resize_dos_memory, __dpmi_relock_real_mode_region, Alphabetical List
@unnumberedsec __dpmi_reset_debug_watchpoint
@c From file ./dpmi/api/d0b03.txh
@findex __dpmi_reset_debug_watchpoint
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_reset_debug_watchpoint(unsigned long _handle);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0b03

Resets a watchpoint given its handle in @var{_handle}.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_resize_dos_memory, __dpmi_resize_linear_memory, __dpmi_reset_debug_watchpoint, Alphabetical List
@unnumberedsec __dpmi_resize_dos_memory
@c From file ./dpmi/api/d0102.txh
@findex __dpmi_resize_dos_memory
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_resize_dos_memory(int _selector, int _newpara,
                             int *_ret_max);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0102

This function resizes a dos memory block.  Remember to pass the
selector, and not the segment.  If this call fails, @var{_ret_max}
contains the largest number of paragraphs available.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_resize_linear_memory, __dpmi_resize_memory, __dpmi_resize_dos_memory, Alphabetical List
@unnumberedsec __dpmi_resize_linear_memory
@c From file ./dpmi/api/d0505.txh
@findex __dpmi_resize_linear_memory
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_resize_linear_memory(__dpmi_meminfo *info, int commit);
@end smallexample

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0505 (DPMI 1.0 only).  Not supported by CWSDPMI and
Windows.

This function resizes a memory block.  Pass the handle and new size.
Bit 0 of @var{commit} is 1 for committed pages; bit 1 is 1 to automatically
update descriptors.  It returns a new handle and base address.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_resize_memory, __dpmi_segment_to_descriptor, __dpmi_resize_linear_memory, Alphabetical List
@unnumberedsec __dpmi_resize_memory
@c From file ./dpmi/api/d0503.txh
@findex __dpmi_resize_memory
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_resize_memory(__dpmi_meminfo *_info);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0503

This function changes the size of a virtual memory block.  You must
pass the handle and size fields.  It may change the base address also;
beware of debugging breakpoints and locked memory.  It will return a
new handle.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_segment_to_descriptor, __dpmi_serialize_on_shared_memory, __dpmi_resize_memory, Alphabetical List
@unnumberedsec __dpmi_segment_to_descriptor
@c From file ./dpmi/api/d0002.txh
@findex __dpmi_segment_to_descriptor
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_segment_to_descriptor(int _segment);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0002

This function returns a selector that maps to what the real-mode
segment provided would have referenced.  Warning: this is a scarce
resource.

@subheading Return Value

-1 on error, else the selector.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
short video = __dpmi_segment_to_descriptor(0xa000);
movedata(_my_ds(), buffer, video, 0, 320*200);
@end example

@c -----------------------------------------------------------------------------
@node __dpmi_serialize_on_shared_memory, __dpmi_set_coprocessor_emulation, __dpmi_segment_to_descriptor, Alphabetical List
@unnumberedsec __dpmi_serialize_on_shared_memory
@c From file ./dpmi/api/d0d02.txh
@findex __dpmi_serialize_on_shared_memory
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_serialize_on_shared_memory(unsigned long handle, int flags);
@end smallexample

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0d02 (DPMI 1.0 only).  Not supported by CWSDPMI and
Windows.

This function serializes access to a shared memory block whose handle is
given in @var{handle}.  The bit-mapped variable @var{flags} defines the
following bits:

@table @asis
@item bit 0
If set, return immediately if serialization is unavailable.  If cleared,
the program is suspended until the serialization becomes available.

@item bit 1
If set, perform shared serialization.  If cleared, perform exclusive
serialization.

@item bits 2-15
Reserved (should be zero).
@end table

An @dfn{exclusive serialization} blocks @emph{any} serialization
attempts for the same memory block from other virtual machines.  A
@dfn{shared serialization} blocks only @emph{exclusive} serialization
attempts from other virtual machines.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_set_coprocessor_emulation, __dpmi_set_debug_watchpoint, __dpmi_serialize_on_shared_memory, Alphabetical List
@unnumberedsec __dpmi_set_coprocessor_emulation
@c From file ./dpmi/api/d0e01.txh
@findex __dpmi_set_coprocessor_emulation
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_set_coprocessor_emulation(int flags);
@end smallexample

@subheading Description

Please refer to @ref{DPMI Specification}, for details on DPMI
function call operation.  Also see @ref{DPMI Overview}, for general
information.

DPMI function AX = 0x0e01 (DPMI v1.0 only, but supported by most
@w{DPMI v0.9} servers, including CWSDPMI, Windows, and QDPMI).

This function sets the co-processor emulation state as specified by
@var{flags}.  The only two used bits in @var{flags} are:

@table @code
@item bit 0
If set, enable the co-processor.  If reset, disable the co-processor.

@item bit 1
If set, the emulation of the floating-point instructions will be done by
the calling application.
@end table

DJGPP programs using one of the provided emulators should generally call
this function with an argument of 2.  (The DJGPP startup code does that
automatically if no co-processor is detected.)

@subheading Return Value

-1 on errors, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_set_debug_watchpoint, __dpmi_set_descriptor, __dpmi_set_coprocessor_emulation, Alphabetical List
@unnumberedsec __dpmi_set_debug_watchpoint
@c From file ./dpmi/api/d0b00.txh
@findex __dpmi_set_debug_watchpoint
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_set_debug_watchpoint(__dpmi_meminfo *_info, int _type);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0b00

Set a debug breakpoint.  Type is 0 for execute, 1 for write, and 2 for
access.  Fill in address and size (1,2,4 bytes).  Server fills in
handle.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_set_descriptor, __dpmi_set_descriptor_access_rights, __dpmi_set_debug_watchpoint, Alphabetical List
@unnumberedsec __dpmi_set_descriptor
@c From file ./dpmi/api/d000c.txh
@findex __dpmi_set_descriptor
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_set_descriptor(int _selector, void *_buffer);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x000c

This function sets the parameters of the selector @var{_selector} by
copying the contents of the 8-byte buffer pointed to by @var{_buffer}
into the LDT entry of the selector's descriptor.
@xref{__dpmi_get_descriptor}, for the description of the contents of the
8-byte buffer.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_set_descriptor_access_rights, __dpmi_set_extended_exception_handler_vector_pm, __dpmi_set_descriptor, Alphabetical List
@unnumberedsec __dpmi_set_descriptor_access_rights
@c From file ./dpmi/api/d0009.txh
@findex __dpmi_set_descriptor_access_rights
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_set_descriptor_access_rights(int _selector, int _rights);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0009

This sets the access rights of @var{_selector} to @var{_rights}.

The meaning of the individual bit fields of @var{_rights} is described
below.  For more details, please refer to @ref{__dpmi_get_descriptor}.

@example
---- ---- ---- ---X = 0=not accessed, 1=accessed
---- ---- ---- --X- = data: 0=read, 1=r/w; code: 1=readable
---- ---- ---- -X-- = data: 0=expand-up, 1=expand-down; 
                      code: 0=non-conforming
---- ---- ---- X--- = 0=data, 1=code
---- ---- ---1 ---- = must be 1
---- ---- -XX- ---- = privilege level (must equal CPL)
---- ---- X--- ---- = 0=absent, 1=present
---X ---- ---- ---- = available for the user
--0- ---- ---- ---- = must be 0
-X-- ---- ---- ---- = 0=16-bit 1=32-bit
X--- ---- ---- ---- = 0=byte granular (small) 1=page-granular (big)
@end example

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_set_extended_exception_handler_vector_pm, __dpmi_set_extended_exception_handler_vector_rm, __dpmi_set_descriptor_access_rights, Alphabetical List
@unnumberedsec __dpmi_set_extended_exception_handler_vector_pm
@c From file ./dpmi/api/d0212.txh
@findex __dpmi_set_extended_exception_handler_vector_pm
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_set_extended_exception_handler_vector_pm(
        int vector, __dpmi_paddr *address
);
@end smallexample

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0212 (DPMI 1.0 only).  Not supported by CWSDPMI and
Windows.

This function installs a handler for protected-mode exceptions.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_set_extended_exception_handler_vector_rm, __dpmi_set_multiple_descriptors, __dpmi_set_extended_exception_handler_vector_pm, Alphabetical List
@unnumberedsec __dpmi_set_extended_exception_handler_vector_rm
@c From file ./dpmi/api/d0213.txh
@findex __dpmi_set_extended_exception_handler_vector_rm
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_set_extended_exception_handler_vector_rm(
        int vector, __dpmi_paddr *address
);
@end smallexample

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0213 (DPMI 1.0 only).  Not supported by CWSDPMI and
Windows.

This function installs a handler for real-mode exceptions.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_set_multiple_descriptors, __dpmi_set_page_attributes, __dpmi_set_extended_exception_handler_vector_rm, Alphabetical List
@unnumberedsec __dpmi_set_multiple_descriptors
@c From file ./dpmi/api/d000f.txh
@findex __dpmi_set_multiple_descriptors
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_set_multiple_descriptors(int count, void *buffer);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x000f (DPMI 1.0 only).  Not supported by CWSDPMI and
Windows.

This function sets multiple descriptors.  Buffer usage is like in
@code{__dpmi_get_multiple_descriptors}
(@pxref{__dpmi_get_multiple_descriptors}), but the caller fills in
everything before calling.

@subheading Return Value

Returns @var{count} if successful, the negative of the number of
descriptors set if failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_set_page_attributes, __dpmi_set_processor_exception_handler_vector, __dpmi_set_multiple_descriptors, Alphabetical List
@unnumberedsec __dpmi_set_page_attributes
@c From file ./dpmi/api/d0507.txh
@findex __dpmi_set_page_attributes
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_set_page_attributes(__dpmi_meminfo *info, short *buffer);
@end smallexample

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0507 (DPMI 1.0 only).  Supported by CWSDPMI, but
not by Windows.

This function sets attributes of a number of pages.  Pass handle in
@code{@var{info}->handle}, offset within block in
@code{@var{info}->address}, and number of pages in
@code{@var{info}->count}.  @var{buffer} points to an array of 16-bit
words which specify the new attributes.
@xref{__dpmi_get_page_attributes}, for the definition of the page
attribute word.

The DJGPP startup code calls this function to uncommit the so-called
@dfn{null page}, the first 4KB of the program's address space.  This
causes @code{NULL} pointer dereferences, a frequent programmatic error,
to trigger a Page Fault exception, rather than go unnoticed.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_set_processor_exception_handler_vector, __dpmi_set_protected_mode_interrupt_vector, __dpmi_set_page_attributes, Alphabetical List
@unnumberedsec __dpmi_set_processor_exception_handler_vector
@c From file ./dpmi/api/d0203.txh
@findex __dpmi_set_processor_exception_handler_vector
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_set_processor_exception_handler_vector(
        int _vector, __dpmi_paddr *_address
);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0203

This function installs a handler for protected mode exceptions (not
interrupts).  You must pass a selector:offset pair.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_set_protected_mode_interrupt_vector, __dpmi_set_real_mode_interrupt_vector, __dpmi_set_processor_exception_handler_vector, Alphabetical List
@unnumberedsec __dpmi_set_protected_mode_interrupt_vector
@c From file ./dpmi/api/d0205.txh
@findex __dpmi_set_protected_mode_interrupt_vector
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_set_protected_mode_interrupt_vector(int _vector,
                                               __dpmi_paddr *_address);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0205

This function installs a protected-mode interrupt (not exception)
handler.  You must pass a selector:offset pair.  Hardware interrupts
will always be reflected to protected mode if you install a handler.
You must explicitly @code{sti} before @code{iret} because @code{iret}
won't always restore interrupts in a virtual environment.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_set_real_mode_interrupt_vector, __dpmi_set_segment_base_address, __dpmi_set_protected_mode_interrupt_vector, Alphabetical List
@unnumberedsec __dpmi_set_real_mode_interrupt_vector
@c From file ./dpmi/api/d0201.txh
@findex __dpmi_set_real_mode_interrupt_vector
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_set_real_mode_interrupt_vector(int _vector,
                                          __dpmi_raddr *_address);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0201

This function sets a real-mode interrupt vector.  You must pass a
segment:offset pair, not a selector.

Bits [31:8] in the vector number are silently ignored.

@subheading Return Value

Zero.  This function always works.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_set_segment_base_address, __dpmi_set_segment_limit, __dpmi_set_real_mode_interrupt_vector, Alphabetical List
@unnumberedsec __dpmi_set_segment_base_address
@c From file ./dpmi/api/d0007.txh
@findex __dpmi_set_segment_base_address
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_set_segment_base_address(int _selector, unsigned _address);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0007

This function sets the base address of the @var{_selector} to
@var{_address}.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_set_segment_limit, __dpmi_simulate_real_mode_interrupt, __dpmi_set_segment_base_address, Alphabetical List
@unnumberedsec __dpmi_set_segment_limit
@c From file ./dpmi/api/d0008.txh
@findex __dpmi_set_segment_limit
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_set_segment_limit(int _selector, unsigned _address);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0008

This function sets the highest valid address in the segment referenced
by @var{_selector}.  For example, if you pass 0xfffff, the highest
valid address is 0xfffff.  Note: if you pass a number <= 64K, the
segment changes to "non-big", and may cause unexpected problems.  Limits
for segments larger than 1MB must have their low 12 bits set.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_simulate_real_mode_interrupt, __dpmi_simulate_real_mode_procedure_iret, __dpmi_set_segment_limit, Alphabetical List
@unnumberedsec __dpmi_simulate_real_mode_interrupt
@c From file ./dpmi/api/d0300.txh
@findex __dpmi_simulate_real_mode_interrupt
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_simulate_real_mode_interrupt(int _vector,
                                        __dpmi_regs *_regs);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0300

This function performs a software interrupt in real mode after filling
in @emph{all} the registers from the given structure.  You @emph{must}
set %ss, %esp, and %eflags to valid real-mode values or zero, unlike
@ref{__dpmi_int}.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_simulate_real_mode_procedure_iret, __dpmi_simulate_real_mode_procedure_retf, __dpmi_simulate_real_mode_interrupt, Alphabetical List
@unnumberedsec __dpmi_simulate_real_mode_procedure_iret
@c From file ./dpmi/api/d0302.txh
@findex __dpmi_simulate_real_mode_procedure_iret
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_simulate_real_mode_procedure_iret(__dpmi_regs *_regs);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0302

This function switches to real mode, filling in @emph{all} the
registers from the structure.  ss:sp and flags must be valid or zero.
The called function must return with an @code{iret}.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_simulate_real_mode_procedure_retf, __dpmi_simulate_real_mode_procedure_retf_stack, __dpmi_simulate_real_mode_procedure_iret, Alphabetical List
@unnumberedsec __dpmi_simulate_real_mode_procedure_retf
@c From file ./dpmi/api/d0301.txh
@findex __dpmi_simulate_real_mode_procedure_retf
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_simulate_real_mode_procedure_retf(__dpmi_regs *_regs);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0301

This function switches to real mode with @emph{all} the registers set
from the structure, including cs:ip.  The function called should
return with a @code{retf}.  ss:sp and flags must be set to valid
values or zero.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_simulate_real_mode_procedure_retf_stack, __dpmi_terminate_and_stay_resident, __dpmi_simulate_real_mode_procedure_retf, Alphabetical List
@unnumberedsec __dpmi_simulate_real_mode_procedure_retf_stack
@c From file ./dpmi/api/d0301_s.txh
@findex __dpmi_simulate_real_mode_procedure_retf_stack
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_simulate_real_mode_procedure_retf_stack(
        __dpmi_regs *_regs,
        int stack_words_to_copy, const void *stack_data
);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0301

This function switches to real mode with @emph{all} the registers set
from the structure, including cs:ip.  The function called should
return with a @code{retf}.  ss:sp and flags must be set to valid
values or zero.

You may optionally specify data to be copied to the real-mode stack,
to pass arguments to real-mode procedures with stack-based calling
conventions.  If you don't want to copy data to the real mode stack,
pass 0 for @var{stack_words_to_copy}, and @code{NULL} for
@var{stack_bytes}.

Note that the amount of stack data to be copied should be given in units
of 16-bit words, not in bytes.  This is defined by the underlying DPMI
function.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_terminate_and_stay_resident, __dpmi_unlock_linear_region, __dpmi_simulate_real_mode_procedure_retf_stack, Alphabetical List
@unnumberedsec __dpmi_terminate_and_stay_resident
@c From file ./dpmi/api/d0c01.txh
@findex __dpmi_terminate_and_stay_resident
@subheading Syntax

@smallexample
#include <dpmi.h>

int __dpmi_terminate_and_stay_resident(int return_code, 
                                       int paragraphs_to_keep);
@end smallexample

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0c01 (DPMI 1.0 only).  Not supported by CWSDPMI and
Windows.

This function terminates the calling program, but leaves it resident in
memory.  @var{return_code} specifies which value to return to the OS.
@var{paragraphs_to_keep} specifies the number of paragraphs of DOS
(conventional) memory to keep; it should be either zero or 6 or more.
Note that any protected-mode memory remains allocated to the program
unless explicitly freed before calling this function.

The calling program @strong{must} call the function
@code{__dpmi_install_resident_service_provider_callback} before this
one, otherwise it will be terminated instead of going TSR.
@xref{__dpmi_install_resident_service_provider_callback}.

@subheading Return Value

This call does not return.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_unlock_linear_region, __dpmi_yield, __dpmi_terminate_and_stay_resident, Alphabetical List
@unnumberedsec __dpmi_unlock_linear_region
@c From file ./dpmi/api/d0601.txh
@findex __dpmi_unlock_linear_region
@subheading Syntax

@example
#include <dpmi.h>

int __dpmi_unlock_linear_region(__dpmi_meminfo *_info);
@end example

@subheading Description

Please refer to the DPMI Specification (@pxref{DPMI Specification})
for details on DPMI function call operation.  Also see
the DPMI Overview (@pxref{DPMI Overview}) for general information.

DPMI function AX = 0x0601

This function unlocks virtual memory.  Pass address and size (in bytes).

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __dpmi_yield, dprintf, __dpmi_unlock_linear_region, Alphabetical List
@unnumberedsec __dpmi_yield
@c From file ./dpmi/api/2f_1680.txh
@findex __dpmi_yield
@subheading Syntax

@example
#include <dpmi.h>

void __dpmi_yield(void);
@end example

@subheading Description

@code{__dpmi_yield} calls function 1680h of the interrupt 2Fh, which
tells the task manager in a multitasking environment that the calling
program doesn't need the rest of its time slice.  The task manager will
then preempt the calling program and switch to another task that is
ready to run.

This function should be called in busy-wait loops, like when a program
waits for user input via keyboard, after it finds the keyboard buffer
empty, to enhance overall performance in a multitasking environment.

@subheading Return Value

None.  If the call isn't supported by the environment, like when running
on plain DOS, @code{errno} is set to @code{ENOSYS}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node dprintf, DTTOIF, __dpmi_yield, Alphabetical List
@unnumberedsec dprintf
@c From file ./posix/stdio/dprintf.txh
@findex dprintf
@subheading Syntax

@example
#include <stdio.h>

int dprintf(int file_desc, const char *format, ...);
@end example

@subheading Description

The function @code{dprintf} is an exact analog of @code{fprintf} (@pxref{fprintf}),
except that it output to a file descriptor @var{file_desc}
instead of to a stdio stream.

@subheading Return Value

The number of characters written is returned; otherwise EOF
is returned to flag encoding or buffer space errors.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable

@c -----------------------------------------------------------------------------
@node DTTOIF, dup, dprintf, Alphabetical List
@unnumberedsec DTTOIF
@c From file ./posix/dirent/readdir.txh
@findex DTTOIF
@subheading Syntax

@example
#include <dirent.h>

struct dirent *de;
mode_t file_mode = DTTOIF(de->d_type)
@end example

@subheading Description

This macro converts the @code{d_type} member of a @code{struct dirent}
variable, as returned by @code{readdir} (@pxref{readdir}) to an
equivalent value of the @code{st_mode} member of a @code{struct stat}
variable (@pxref{stat}).

Note that the access rights are not set in the result returned by this
macro.  Only the file-type information is copied.

@subheading Return Value

The file's mode bits are returned.  If the argument has the value
@code{DT_UNKNOWN}, the result will be @code{S_IFREG}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
This macro is available on systems which support the @code{d_type} member in @code{struct dirent}.
@end enumerate
@c -----------------------------------------------------------------------------
@node dup, dup2, DTTOIF, Alphabetical List
@unnumberedsec dup
@c From file ./posix/unistd/dup.txh
@findex dup
@subheading Syntax

@example
#include <unistd.h>

int dup(int old_handle);
@end example

@subheading Description

This function duplicates the given file handle.  Both handles refer to
the same file and file pointer. 

@subheading Return Value

The new file handle, or -1 if error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
do_file(dup(fileno(stdin)));
@end example

@c -----------------------------------------------------------------------------
@node dup2, __dup_fd_properties, dup, Alphabetical List
@unnumberedsec dup2
@c From file ./posix/unistd/dup2.txh
@findex dup2
@subheading Syntax

@example
#include <unistd.h>

int dup2(int existing_handle, int new_handle);
@end example

@subheading Description

This call causes @var{new_handle} to refer to the same file and file
pointer as @var{existing_handle}.  If @var{new_handle} is an open file,
it is closed. 

@subheading Return Value

The new handle, or -1 on error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
/* copy new file to stdin stream */
close(0);
dup2(new_stdin, 0);
close(new_stdin);
@end example

@c -----------------------------------------------------------------------------
@node __dup_fd_properties, _dxe_load, dup2, Alphabetical List
@unnumberedsec __dup_fd_properties
@c From file ./dos/io/fd_props.txh
@findex __dup_fd_properties
@subheading Syntax

@example
#include <libc/fd_props.h>

void __dup_fd_properties(int existing_handle, int new_handle);

@end example

@subheading Description

Causes the new file descriptor @var{new_handle} to refer to the same
@code{fd_properties} struct as @var{existing_handle}.
This internal function is called by @code{dup} and @code{dup2}.

For more information, see @code{__set_fd_properties}
(@pxref{__set_fd_properties}) and
@code{__clear_fd_properties} (@pxref{__clear_fd_properties}).

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _dxe_load, DXE_macros, __dup_fd_properties, Alphabetical List
@unnumberedsec _dxe_load
@c From file ./dxe/dxeload.txh
@findex _dxe_load
@subheading Syntax

@example
#include <sys/dxe.h>

void *_dxe_load(char *dxe_filename);
@end example

@subheading Description

This function loads a dynamic executable image, whose file name is
pointed to by @var{dxe_filename}, into memory and returns the
entry point for the symbol associated with the image.  The symbol may point
to a structure or a function.

@subheading Return Value

0 on failure, the address of the loaded symbol on success.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  static int (*add)(int a, int b);

  add = _dxe_load("add.dxe");
  if (add == 0)
    printf("Cannot load add.dxe\n");
  else
    printf("Okay, 3 + 4 = %d\n", add(3,4));
@end example

@c -----------------------------------------------------------------------------
@node DXE_macros, ecvt, _dxe_load, Alphabetical List
@unnumberedsec DXE_macros
@c From file ./dxe/dlregsym.txh
@subheading Syntax

@example
#include <sys/dxe.h>

	DXE_EXPORT_TABLE(name)
	DXE_EXPORT_TABLE_AUTO(name)
	DXE_EXPORT(symbol)
	DXE_EXPORT_ASM(_symbol)
	DXE_EXPORT_END

@end example

@subheading Description

These macros allows you to define a table of symbols that are going to be
exported into subsequently loaded modules.  If you use
@code{DXE_EXPORT_TABLE_AUTO} instead of @code{DXE_EXPORT_TABLE} the table will
be automatically registered with the dynamic loader during program startup
(thus you don't need to call @code{dlregsym(name)} manually).

@example
	DXE_DEMAND(name);
@end example

This macro declares the two functions that are present if you are statically
linking against a dynamic library (see the @command{dxe3gen} section for
details on static linking).  Note that @var{name} should be in capitals with
any illegal character converted to underscore.  After declaring the module with
the above macro, you can call the @code{dlload_NAME} and @code{dlunload_NAME}
functions to dynamically load and unload the statically linked dynamic library.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable

@c -----------------------------------------------------------------------------
@node ecvt, ecvtbuf, DXE_macros, Alphabetical List
@unnumberedsec ecvt
@c From file ./compat/stdlib/itoa.txh
@findex ecvt
@subheading Syntax

@example
#include <stdlib.h>

char * ecvt (double value, int ndigits, int *decpt, int *sign)
@end example

@subheading Description

This function converts the @var{value} into a null-terminated string,
and returns a pointer to that string.

@code{ecvt} works exactly like @code{ecvtbuf} (@pxref{ecvtbuf}), except
that it generates the string in an internal static buffer which is
overwritten on each call.

@subheading Return Value

A pointer to the generated string.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable



@c -----------------------------------------------------------------------------
@node ecvtbuf, edi_init, ecvt, Alphabetical List
@unnumberedsec ecvtbuf
@c From file ./compat/stdlib/itoa.txh
@findex ecvtbuf
@subheading Syntax

@example
#include <stdlib.h>

char * ecvtbuf (double value, int ndigits, int *decpt, int *sign,
                char *buf)
@end example

@subheading Description

This function converts its argument @var{value} into a null-terminated
string of @var{ndigits} digits in @var{buf}.  @var{buf} should have
enough space to hold at least @code{@var{ndigits} + 1} characters.

The produced string in @var{buf} does @emph{not} include the decimal
point.  Instead, the position of the decimal point relative to the
beginning of @var{buf} is stored in an integer variable whose address is
passed in @var{decpt}.  Thus, if @var{buf} is returned as ``1234'' and
@var{*decpt} as 1, this corresponds to a value of 1.234; if @var{*decpt}
is -1, this corresponds to a value of 0.01234, etc.

The sign is also not included in @var{buf}'s value.  If @var{value} is
negative, @code{ecvtbuf} puts a nonzero value into the variable whose
address is passed in @var{sign}; otherwise it stores zero in
@var{*sign}.

The least-significant digit in @var{buf} is rounded.

@code{ecvtbuf} produces the string ``NaN'' if @var{value} is a NaN, and
``Inf'' or ``Infinity'' if @var{value} is an infinity (the longer form
is produced when @var{ndigits} is 8 or more).

@subheading Return Value

A pointer to @var{buf}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  #include <stdlib.h>
  #include <stdio.h>
  #include <math.h>

  char vbuf[20];
  int esign, edecpt;

  ecvtbuf (M_PI, 5, &edecpt, &esign, buf)
  /* This will print " 31416".  */
  printf ("%c%s", esign ? '-' : ' ', buf);
@end example


@c -----------------------------------------------------------------------------
@node edi_init, enable, ecvtbuf, Alphabetical List
@unnumberedsec edi_init
@c From file ./debug.txh
@findex edi_init
@subheading Syntax

@example
#include <debug/dbgcom.h>

void edi_init (jmp_buf start_state);
@end example

@subheading Description

This function is part of the DJGPP @dfn{debugging support}.  It should be
called after a call to @code{v2loadimage} (@pxref{v2loadimage}) which
loads an executable program as a debuggee.  @code{edi_init} then takes
care of initializing the data structures which need to be set before the
debugger can set breakpoints and run the debuggee.

The argument @var{start_state} is usually set by a preceding call to
@code{v2loadimage}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
 if (v2loadimage (exec_file, cmdline, start_state))
   @{
      printf ("Load failed for image %s\n", exec_file);
      exit (1);
   @}

  edi_init (start_state);
@end example

@c -----------------------------------------------------------------------------
@node enable, endgrent, edi_init, Alphabetical List
@unnumberedsec enable
@c From file ./pc_hw/hwint/enable.txh
@findex enable
@subheading Syntax

@example
#include <dos.h>

int enable(void);
@end example

@subheading Description

This function enables interrupts.

@xref{disable}.

@subheading Return Value

Returns nonzero if the interrupts were already enabled, zero if they
had been disabled before this call.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
int ints_were_enabled;

ints_were_enabled = enable();
. . . do some stuff . . .
if (!ints_were_enabled)
  disable();
@end example

@c -----------------------------------------------------------------------------
@node endgrent, endmntent, enable, Alphabetical List
@unnumberedsec endgrent
@c From file ./posix/grp/getgrent.txh
@findex endgrent
@subheading Syntax

@example
#include <grp.h>

void endgrent(void);
@end example

@subheading Description

This function should be called after all calls to @code{getgrent},
@code{getgrgid}, or @code{getgrnam}. 

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@xref{getgrent}.

@c -----------------------------------------------------------------------------
@node endmntent, endpwent, endgrent, Alphabetical List
@unnumberedsec endmntent
@c From file ./compat/mntent/mntent.txh
@findex endmntent
@subheading Syntax

@example
#include <mntent.h>

int endmntent(FILE *filep);
@end example

@subheading Description

This function should be called after the last call to @code{getmntent}
(@pxref{getmntent}).

@subheading Return Value

This function always returns one.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node endpwent, errno, endmntent, Alphabetical List
@unnumberedsec endpwent
@c From file ./posix/pwd/pwent.txh
@findex endpwent
@subheading Syntax

@example
#include <pwd.h>

void endpwent(void);
@end example

@subheading Description

This function should be called after the last call to getpwent (@pxref{getpwent}).

@subheading Return Value

None.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node errno, exec*, endpwent, Alphabetical List
@unnumberedsec errno
@c From file ./ansi/errno/errno.txh
@vindex errno
@subheading Syntax

@example
#include <errno.h>

extern int errno;
@end example

@subheading Description

This variable is used to hold the value of the error of the last
function call.  The value might be one of the following:

@table @code
@item 0

No Error.  Library functions never set @code{errno} to zero, but the
startup code does that just before calling @code{main} (this is ANSI C
requirement).

@item 1

EDOM -- Numerical input to a function is out of range.

@item 2

ERANGE -- Numerical output of a function is out of range.

@item 3

E2BIG -- Argument list too long.  @code{system} and the functions from
the @code{spawn} family assign this to @code{errno} when the command
line is too long (longer than 126-character limit when invoking
non-DJGPP programs, or longer than the transfer buffer size when
invoking DJGPP programs).

@item 4

EACCES -- Permission denied.  Attempt to write to a read-only file, or
remove a non-empty directory, or open a directory as if it were a file,
etc.  In essence, it's a DOS way of saying "You can't do that, but I'm
too stupid to know why."

@item 5

EAGAIN -- Resource temporarily unavailable, try again later.  Almost
never used in DJGPP, except when DOS returns error code 3Dh ("network
print queue full") 81h (NetWare4 "CWait children still running") or 9Bh
(NetWare4 "unable to create another TCB").

@item 6

EBADF -- Bad file descriptor: an invalid file handle passed to a library
function.

@item 7

EBUSY -- Resource busy.  Attempt to remove current directory (including
current directory on another drive), or when a networked resource, such
as a drive, is in use by another process.

@item 8

ECHILD -- No child processes.  Returned by @code{wait} and
@code{waitpid}, and by NetWare-related calls.

@item 9

EDEADLK -- Resource deadlock avoided.  Never used in DJGPP.

@item 10

EEXIST -- File exists.  Returned by @code{open} and @code{mkdir} when a
file or directory by that name already exists.

@item 11

EFAULT -- Bad address.  A function was passed a bad pointer (like a
@code{NULL} pointer).

@item 12

EFBIG -- File too large.  Never used in DJGPP.

@item 13

EINTR -- Interrupted system call.  @code{system} and the functions of
the @code{spawn} family use that when the child program was interrupted
by @kbd{Ctrl-@key{C}}.  Also, when DOS returns the "fail on INT 24h"
error code.

@item 14

EINVAL -- Invalid argument.  Any case when any argument to a library
function is found to be invalid.  Examples include invalid drive number,
"." or ".." as one of the arguments to @code{rename}, syntax errors in
the command line passed to @code{system}, etc.

@item 15

EIO -- Input or output error.  Low-level error in I/O operation, like
bad disk block, damaged FAT, etc.

@item 16

EISDIR -- Is a directory: an attempt to do something with a directory
which is only allowed with regular files.  DOS usually returns
@code{EACCES} in these cases, but DJGPP sometimes assigns @code{EISDIR}
to @code{errno}, like when @code{rename} is called to move a regular
file over a directory, or when @code{system} or one of the @code{spawn*}
functions are passed a name of a directory instead of an executable
program.

@item 17

EMFILE -- Too many open files in system (no more handles available).
This usually means that the number specified by the @samp{FILES=}
directive in @file{CONFIG.SYS} is too small.

@item 18

EMLINK -- Too many links.  Not used in DJGPP (as DOS doesn't support
hard links).

@item 19

ENAMETOOLONG -- File name too long (longer than @code{FILENAME_MAX},
defined in @file{stdio.h}).

@item 20

ENFILE -- Too many open files.  Never used in DJGPP.

@item 21

ENODEV -- No such device.  Attempt to access an invalid drive, or an
invalid operation for the type of drive.

@item 22

ENOENT -- No such file or directory.

@item 23

ENOEXEC -- Unable to execute file.  Returned by @code{_dxe_load} (when
the argument names a file that isn't a valid DXE), and by
NetWare-related calls which run programs remotely.

@item 24

ENOLCK -- No locks available.  Returned when the DOS file-locking
functions cannot lock more files (due to overflow of the sharing
buffer).

@item 25

ENOMEM -- Not enough memory.  Note that, unlike your expectations,
@code{malloc} does NOT set @code{errno} to @code{ENOMEM}; however,
several library functions that use @code{malloc} will do that when it
returns a @code{NULL} pointer.

@item 26

ENOSPC -- No space left on drive.  DOS usually doesn't return this
error, but @code{write} and @code{_write} do this for it, when they
detect a full disk condition.

@item 27

ENOSYS -- Function not implemented.  Any system call that isn't
supported by the underlying OS, like an LFN function when running on
plain DOS.

@item 28

ENOTDIR -- Not a directory.  DOS never returns this code, but some
library functions, like @code{rename} and @code{_truename}, do that if
they expect a valid directory pathname, but get either an invalid
(e.g. empty) pathname or a file that is not a directory.

@item 29

ENOTEMPTY -- Directory not empty.  DOS never returns this code, but
@code{rename} does, when it is called to move a directory over an
existing non-empty directory.

@item 30

ENOTTY -- Inappropriate I/O control operation.  The @dfn{termios}
functions set @code{errno} to this when called on a device that is not a
TTY.

@item 31

ENXIO -- No such device or address.  An operation attempted to reference
a device (not a disk drive) that is invalid, or non-existent, or access
a disk drive that exists but is empty.

@item 32

EPERM -- Operation not permitted.  Examples include: sharing or file
lock violations; denial of access to networked resources; expired
password or illegal login attempts via a network; too many or duplicate
network redirections; etc.

@item 33

EPIPE -- Broken pipe: attempt to write to a pipe with nobody to read
it.  This never happens in DJGPP.

@item 34

EROFS -- Read-only file system: attempt to write to a read-only disk.
Unfortunately, DOS almost never returns this code.

@item 35

ESPIPE -- Invalid seek: attempt to seek on a pipe.  Never happens in
DJGPP, except for NetWare-related operations, since pipes are simulated
with regular files in MS-DOS, and therefore are always seekable.

@item 36

ESRCH -- No such process.  Not used in DJGPP.

@item 37

EXDEV -- Improper link.  An attempt to rename a file across drives
or create a cross-device hardlink.

@item 38

ENMFILE -- No more files.  @code{findfirst} and @code{findnext} assign
this to @code{errno} when they exhaust the files in the directory.
@code{readdir} does that as well.

@item 39

ELOOP -- Too many levels of symbolic links.  Can be set virtually by any
file handling function in library. Usually means encountered link loop
(link1 -> link2, link2 -> link1).

@item 40

EOVERFLOW -- Value too large.  @code{filelength} can assign this to
@code{errno} when a file's length is larger than @math{2^31-2}
(@pxref{filelength}).  @code{lfilelength} can assign this to @code{errno}
when a file's length is larger than @math{2^63-1} (@pxref{lfilelength}).

@item 41

EILSEQ -- Invalid or incomplete multibyte or wide character.

@end table


@xref{perror}.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node exec*, __exit, errno, Alphabetical List
@unnumberedsec exec*
@c From file ./posix/unistd/exec.txh
@findex execl
@findex execle
@findex execlp
@findex execlpe
@findex execv
@findex execve
@findex execvp
@findex execvpe
@subheading Syntax

@example
#include <unistd.h>

int execl(const char *path, const char *argv0, ...);
int execle(const char *path, const char *argv0, ...
           /*, char *const envp[] */);
int execlp(const char *path, const char *argv0, ...);
int execlpe(const char *path, const char *argv0, ...
            /*, char *const envp[] */);

int execv(const char *path, char *const argv[]);
int execve(const char *path, char *const argv[], char *const envp[]);
int execvp(const char *path, char *const argv[]);
int execvpe(const char *path, char *const argv[], char *const envp[]);
@end example

@subheading Description

These functions operate by calling @code{spawn*} with a type of
@code{P_OVERLAY}.  Refer to @code{spawn*} (@pxref{spawn*})
for a full description. 

@subheading Return Value

If successful, these functions do not return.  If there is an error,
these functions return -1 and set @code{errno} to indicate the error. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
execlp("gcc", "gcc", "-v", "hello.c", 0);
@end example

@c -----------------------------------------------------------------------------
@node __exit, _exit, exec*, Alphabetical List
@unnumberedsec __exit
@c From file ./crt0/crt0.txh
@findex __exit
@subheading Syntax

@example
#include <unistd.h>

void __exit(int exit_code);
@end example

@subheading Description

This is an internal library function which exits the program, returning
@var{exit_code} to the calling process.  No additional processing is
done, and any @code{atexit} functions are not called.  Since hardware
interrupts are not unhooked, this can cause crashes after the program
exits. This function is normally called only by @code{_exit}; do
@emph{not} call it directly.

@subheading Return Value

This function does not return.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node _exit, _Exit, __exit, Alphabetical List
@unnumberedsec _exit
@c From file ./crt0/crt0.txh
@findex _exit
@subheading Syntax

@example
#include <unistd.h>

void _exit(int exit_code);
@end example

@subheading Description

This function exits the program, returning @var{exit_code} to the
calling process.  No additional processing (such as closing file
descriptors or calls to the static destructor functions) is done, and
any @code{atexit} functions are not called; only the hardware interrupt
handlers are unhooked, to prevent system crashes e.g. after a call to
@code{abort}.  This function is normally called only by @code{exit} and
@code{abort}.

@subheading Return Value

This function does not return.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _Exit, exit, _exit, Alphabetical List
@unnumberedsec _Exit
@c From file ./c99/stdlib/_exit.txh
@findex _Exit
@subheading Syntax

@example
#include <stdlib.h>

void _Exit(int exit_code);
@end example

@subheading Description

This function exits the program, returning @var{exit_code} to the
calling process.  No additional processing (such as closing file
descriptors or calls to the static destructor functions) is done, and
any @code{atexit} functions are not called; only the hardware interrupt
handlers are unhooked, to prevent system crashes.

@subheading Return Value

This function does not return.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99 (see note 1); not C89
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable

@noindent
Notes:

@enumerate
@item
Depending on the implementation, @code{_Exit} may do the additional processing described above.

@end enumerate

@subheading Example

@example
if (argc < 4)
@{
  print_usage();
  _Exit(1);
@}
@end example
@c -----------------------------------------------------------------------------
@node exit, exp, _Exit, Alphabetical List
@unnumberedsec exit
@c From file ./ansi/stdlib/exit.txh
@findex exit
@subheading Syntax

@example
#include <stdlib.h>

void exit(int exit_code);
@end example

@subheading Description

This function exits the program, returning @var{exit_code} to the
calling process.  Before exiting, all open files are closed and all
@code{atexit} and @code{on_exit} requests are processed. 

@subheading Return Value

This function does not return.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
if (argc < 4)
@{
  print_usage();
  exit(1);
@}
@end example

@c -----------------------------------------------------------------------------
@node exp, exp10, exit, Alphabetical List
@unnumberedsec exp
@c From file ./ansi/math/exp.txh
@findex exp
@subheading Syntax

@example
#include <math.h>

double exp(double x);
@end example

@subheading Description

This function computes the exponential of @var{x}, @math{e^x}, where
@b{e} is the base of the natural system of logarithms, approximately
2.718281828.

@subheading Return Value

@b{e} to the @var{x} power.  If the value of @var{x} is finite, but so
large in magnitude that its exponential cannot be accurately represented
by a @code{double}, the return value is the nearest representable
@code{double} (possibly, an @code{Inf}), and @code{errno} is set to
@code{ERANGE}.  If @var{x} is either a positive or a negative infinity,
the result is either @code{+Inf} or zero, respectively, and @code{errno}
is not changed.  If @var{x} is a @code{NaN}, the return value is
@code{NaN} and @code{errno} is set to @code{EDOM}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node exp10, exp2, exp, Alphabetical List
@unnumberedsec exp10
@c From file ./compat/math/exp10.txh
@findex exp10
@subheading Syntax

@example
#include <math.h>

double exp10(double x);
@end example

@subheading Description

This function computes 10 to the power of @var{x}, @math{10^x}.

@subheading Return Value

10 to the @var{x} power.  If the value of @var{x} is finite, but so
large in magnitude that @math{10^x} cannot be accurately represented by
a @code{double}, the return value is the nearest representable
@code{double} (possibly, an @code{Inf}), and @code{errno} is set to
@code{ERANGE}.  If @var{x} is either a positive or a negative infinity,
the result is either @code{+Inf} or zero, respectively, and @code{errno}
is not changed.  If @var{x} is a @code{NaN}, the return value is
@code{NaN} and @code{errno} is set to @code{EDOM}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node exp2, expm1, exp10, Alphabetical List
@unnumberedsec exp2
@c From file ./compat/math/exp2.txh
@findex exp2
@subheading Syntax

@example
#include <math.h>

double exp2(double x);
@end example

@subheading Description

This function computes 2 to the power of @var{x}, @math{2^x}.

@subheading Return Value

2 to the @var{x} power.  If the value of @var{x} is finite, but so large
in magnitude that @math{2^x} cannot be accurately represented by a
@code{double}, the return value is is the nearest representable
@code{double} (possibly, an @code{Inf}), and @code{errno} is set to
@code{ERANGE}.  If @var{x} is either a positive or a negative infinity,
the result is either @code{+Inf} or zero, respectively, and @code{errno}
is not changed.  If @var{x} is a @code{NaN}, the return value is
@code{NaN} and @code{errno} is set to @code{EDOM}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node expm1, fabs, exp2, Alphabetical List
@unnumberedsec expm1
@c From file ./compat/math/expm1.txh
@findex expm1
@subheading Syntax

@example
#include <math.h>

double expm1(double x);
@end example

@subheading Description

This function computes the value of @math{e^x - 1}, the exponential of
@var{x} minus 1, where @b{e} is the base of the natural system of
logarithms, approximately 2.718281828.  The result is more accurate than
@code{exp(x) - 1} for small values of @var{x}, where the latter method
would lose many significant digits.

@subheading Return Value

@b{e} raised to the power @var{x}, minus 1.  If the value of @var{x} is
finite, but so large that its exponent would overflow a @code{double},
the return value is @code{Inf}, and @code{errno} is set to
@code{ERANGE}.  If @var{x} is either a positive or a negative infinity,
the result is either @code{+Inf} or -1, respectively, and @code{errno}
is not changed.  If @var{x} is a @code{NaN}, the return value is
@code{NaN} and @code{errno} is set to @code{EDOM}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable

@c -----------------------------------------------------------------------------
@node fabs, _far*, expm1, Alphabetical List
@unnumberedsec fabs
@c From file ./ansi/math/fabs.txh
@findex fabs
@subheading Syntax

@example
#include <math.h>

double fabs(double x);
@end example

@subheading Description

This function computes the absolute value of its argument @var{x}.

@subheading Return Value

@var{x} if @var{x} is positive, else -@var{x}.  Note that in this
context, +0.0 is positive and -0.0 is negative.  Infinities and
@code{NaN}s are returned unchanged, except for the sign.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node _far*, fchdir, fabs, Alphabetical List
@unnumberedsec _far*
@c From file ./pc_hw/farptr/farptr.txh
@findex _farpeekb
@findex _farpeekw
@findex _farpeekl
@findex _farpokeb
@findex _farpokew
@findex _farpokel
@findex _farsetsel
@findex _fargetsel
@findex _farnspeekb
@findex _farnspeekw
@findex _farnspeekl
@findex _farnspokeb
@findex _farnspokew
@findex _farnspokel
@subheading Syntax

@example
#include <sys/farptr.h>

unsigned char _farpeekb(unsigned short selector, unsigned long offset);
unsigned short _farpeekw(unsigned short selector, unsigned long offset);
unsigned long _farpeekl(unsigned short selector, unsigned long offset);

void _farpokeb(unsigned short sel, unsigned long off,
               unsigned char val);
void _farpokew(unsigned short sel, unsigned long off,
               unsigned short val);
void _farpokel(unsigned short sel, unsigned long off,
               unsigned long val);

void _farsetsel(unsigned short selector);
unsigned short _fargetsel(void);

void _farnspokeb(unsigned long offset, unsigned char value);
void _farnspokew(unsigned long offset, unsigned short value);
void _farnspokel(unsigned long offset, unsigned long value);

unsigned char _farnspeekb(unsigned long offset);
unsigned short _farnspeekw(unsigned long offset);
unsigned long _farnspeekl(unsigned long offset);
@end example

@subheading Description

These functions provide the equivalent functionality of "far
pointers" to peek or poke an absolute memory addresses, even though gcc
doesn't understand the keyword "far".  They come in handy when you need
to access memory-mapped devices (like VGA) or some address in lower memory
returned by a real-mode service.
These functions are provided as inline assembler functions, so when
you optimize your program they reduce to only a few opcodes (only one
more than a regular memory access), resulting in very optimal code.

The first two groups of functions take a @var{selector} and an @var{offset}.
This selector is @emph{not} a dos segment.  If you want to access dos
memory, pass _go32_info_block.selector_for_linear_memory (or just
_dos_ds, which is defined in the include file go32.h) as the selector,
and seg*16+ofs as the offset.  For functions which
poke the memory, you should also provide the @var{value} to put there.

The last two groups assume that you've used @code{_farsetsel} to
specify the selector.  You should avoid making any function calls
between @code{_farsetsel} and using these other functions, unless
you're absolutely sure that they won't modify that selector.  This
allows you to optimize loops by setting the selector once outside the
loop, and using the shorter functions within the loop.
You can use @code{_fargetsel} if you want to temporary change the
selector with @code{_farsetsel} and restore it afterwards.

@subheading Return Value

Functions which peek the address return the value at given address.
@code{_fargetsel} returns the current selector.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable

@c -----------------------------------------------------------------------------
@node fchdir, fchmod, _far*, Alphabetical List
@unnumberedsec fchdir
@c From file ./posix/unistd/fchdir.txh
@findex fchdir
@subheading Syntax

@example
#include <unistd.h>

int fchdir(int fd);
@end example

@subheading Description

This function changes the current directory to the directory
described by the file descriptor @var{fd}.

@subheading Return Value

Zero on success, else nonzero and @var{errno} set if error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
int fd;

fd = open("dir", O_RDONLY);
fchdir(fd);
@end example
@c -----------------------------------------------------------------------------
@node fchmod, fchown, fchdir, Alphabetical List
@unnumberedsec fchmod
@c From file ./posix/sys/stat/fchmod.txh
@findex fchmod
@subheading Syntax

@example
#include <sys/stat.h>

int fchmod(int fd, mode_t mode);
@end example

@subheading Description

This function changes the mode (writable or write-only) of the file
opened under the file descriptor @var{fd}.  The value of @var{mode}
can be a combination of one or more of the @code{S_I*} constants
described in the description of the @code{chmod} function (@pxref{chmod}).

Some @code{S_I*} constants are ignored for regular files:

@itemize @bullet
@item
@code{S_I*GRP} and @code{S_I*OTH} are ignored, because DOS/Windows
has no concept of ownership, so all files are considered to belong
to the user;

@item
@code{S_IR*} are ignored, because files are always readable on DOS/Windows.
@end itemize

@code{fchmod} will always succeed for character devices, but the mode
will be ignored.

@code{fchmod} may not be able to change the mode of files that have been
opened using low-level methods.  High-level methods for opening files
include the @code{fopen} (@pxref{fopen}) and @code{open} (@pxref{open})
functions.  Low-level methods include the @code{_open} (@pxref{_open})
and @code{_dos_open} (@pxref{_dos_open}) functions.  In particular,
redirected handles cannot have their mode changed with @code{fchmod}.

@code{fchmod} may also not work as expected under DOS.  For instance,
if a file is opened as read-write, then changed to read-only
with @code{fchmod}, but then written to, then the mode will not
be changed.

This function can be hooked by File System Extensions
(@pxref{File System Extensions}).

@subheading Return Value

Zero if the file exists and the mode was changed, else -1.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
int fd;

fd = open("/tmp/dj.dat", O_RDWR);
fchmod(fd, S_IWUSR|S_IRUSR);
@end example
@c -----------------------------------------------------------------------------
@node fchown, fclose, fchmod, Alphabetical List
@unnumberedsec fchown
@c From file ./compat/unistd/fchown.txh
@findex fchown
@subheading Syntax

@example
#include <unistd.h>

int fchown(int fd, uid_t owner, gid_t group);
@end example

@subheading Description

This function changes the ownership of the open file specified by @var{fd}
to the user ID @var{owner} and group ID @var{group}.

This function does almost nothing under MS-DOS: it just
checks if the handle @code{fd} is valid.  This function can 
be hooked by File System Extensions (@pxref{File System Extensions}).

@subheading Return Value

This function returns zero if the handle is valid, non-zero
otherwise.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable

@c -----------------------------------------------------------------------------
@node fclose, fcntl, fchown, Alphabetical List
@unnumberedsec fclose
@c From file ./ansi/stdio/fclose.txh
@findex fclose
@subheading Syntax

@example
#include <stdio.h>

int fclose(FILE *file);
@end example

@subheading Description

This function closes the given @var{file}.

@subheading Return Value

Zero on success, else @code{EOF}. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
FILE *f = fopen("data", "r");
fprintf(f, "Hello\n");
fclose(f);
@end example

@c -----------------------------------------------------------------------------
@node fcntl, fcvt, fclose, Alphabetical List
@unnumberedsec fcntl
@c From file ./posix/fcntl/fcntl.txh
@findex fcntl
@subheading Syntax

@example
#include <fcntl.h>

int fcntl (int fd, int cmd, ...);
@end example

@subheading Description

This function performs the operation specified by @var{cmd} on
the file open on handle @var{fd}.  The following operations are defined
by the header @code{fcntl.h}:

@table @code
@item F_DUPFD
Returns a file handle that duplicates @var{fd} like @code{dup} does
(@pxref{dup}), except that @code{fcntl} also makes sure the returned
handle is the lowest available handle greater than or equal to the
integer value of the third argument.

@item F_GETFD
Get the @code{FD_CLOEXEC} close-on-exec (a.k.a.@: no-inherit) status of
@var{fd}.  If the returned value has its least-significant bit set, the
file will not be inherited by programs invoked by this process;
otherwise, the file will remain open in the child processes.

Note that only the first 20 handles can be passed to child processes by
DOS/Windows; handles beyond that cannot be inherited.  In addition, the
stub loader of the child DJGPP program will forcibly close handles 19
and 18 (since otherwise it will be unable to read the COFF executable
information and enter protected mode).  Therefore, the current
implementation always returns @code{FD_CLOEXEC} for handles 18 and
above.

For handles less than 18, the call will try to determine the status of
the @code{O_NOINHERIT} flag for that file and will return either
@code{FD_CLOEXEC} if the flag is set, or 0 if the flag is not set.  If
the status of the @code{O_NOINHERIT} flag cannot be determined, the call
will return -1, setting @code{errno} to @code{ENOSYS}.

The no-inherit bit can be set when the file is opened by using the
@code{O_NOINHERIT} in the open flags; see @ref{open}.

@item F_SETFD
Set or unset the close-on-exec flag for the handle @var{fd} using the
LSB of the integer value supplied as the third argument.  Since only the
first 20 handles are passed to child programs, and since the stub loader
of the child DJGPP program will forcibly close handles 19 and 18 (since
otherwise it will be unable to read the COFF executable information and
enter protected mode), the flag can only be set or unset on the first 18
handles.  Attempts to set the flag for handles 18 or above will always
return 0, and attempts to unset the flag for handles 18 or above will
always return -1, setting @code{errno} to @code{ENOSYS}.

For handles less than 18, the call will try to set or unset the
@code{O_NOINHERIT} flag for that file and will return 0 if the flag is
changed.  If the @code{O_NOINHERIT} flag cannot be changed, the call
will return -1, setting @code{errno} to @code{ENOSYS}.
  
@item F_GETFL
Get the open mode and status flags associated with the handle @var{fd}.
The flags are those supported by @code{open} and @code{creat} functions,
like @code{O_RDONLY}, @code{O_APPEND}, etc.

On Windows NT this cannot report the open mode correctly ---
@code{O_RDONLY} is always returned.

@item F_SETFL
Set the open mode and status flags associated with the handle @var{fd}.
This fails in all but one case, and sets @code{errno} to @code{ENOSYS},
since DOS and Windows don't allow changing the descriptor flags after
the file is open.

The one allowed case is for @code{O_NONBLOCK}, since DJGPP doesn't
support it anyway.  That is, calls using @code{F_SETFL} will fail for
all flag values @strong{except} @code{O_NONBLOCK}.

@example
#include <fcntl.h>

ret = fcntl(fd, F_SETFL, O_BINARY); /* This will fail, returning -1  */
                                    /* and setting errno to ENOSYS.  */

ret = fcntl(fd, F_SETFL, O_NONBLOCK); /* This will succeed          */
                                      /* returning 0.               */
@end example

@item F_GETLK
Return the lock structure that prevents obtaining the lock pointed to by
the third argument, or set the @code{l_type} field of the lock structure
to @code{F_UNLCK} if there is no obstruction.  Currently, only the
setting of the @code{l_type} field is provided.  This call will not
return values in the @code{struct flock} parameter identifying what lock
parameters prevent getting the requested lock, since there is no way to
obtain this information from DOS/Windows.  If the lock cannot be
obtained, -1 is returned and @code{errno} is set to the reason (which
will be one of @code{EINVAL}, @code{EBADF}, @code{EACCES} or
@code{ENOLCK}).

Locking of directories is not supported.

@item F_SETLK
Set or clear a file segment lock according to the structure pointed to
by the third argument.  The lock is set when @code{l_type} is
@code{F_RDLCK} (shared lock request) or @code{F_WRLCK} (exclusive lock
request), and the lock is cleared when @code{l_type} is @code{F_UNLCK}.
If the lock is already held, then this call returns -1 and sets
@code{errno} to @code{EACCES}.

The @code{F_RDLCK} value for requesting a read lock is always treated as
if it were @code{F_WRLCK} for a write lock.

This is because DOS/Win9x only supports one kind of lock, and it is the
exclusive kind.

Locking of directories is not supported.

@item F_SETLKW
Same as @code{F_SETLK}, but if the lock is blocked, the call will wait
(using @code{__dpmi_yield}, see @pxref{__dpmi_yield}) until it is
unblocked and the lock can be applied.  This call will @strong{never
exit} if the program making the call is the program which already owns
the lock.

Locking of directories is not supported.

@item F_GETLK64
@item F_SETLK64
@item F_SETLKW64
Each of these does exactly the same function as the non-"64" version,
but the third argument must be of type @code{struct flock64}, which
allows the @var{l_start} and @var{l_len} members to be @code{long long
int} values.  The current code will only use these @code{long long int}
values modulo @math{2^32}, which allows file locking positions up to 4
gigabytes minus 1.  True 64-bit file locking is @strong{not} supported.

The @code{struct flock64} members @var{l_start} and @var{l_len} are
declared to be of type @code{offset_t}, which is in turn typedef'ed to
be a @code{long long}.

Locking of directories is not supported.
@end table

This function can be hooked by the @dfn{Filesystem extensions}, see
@ref{File System Extensions}.  If you don't want this, and you are
calling @code{fcntl} with the @code{F_DUPFD} command, you should use
@code{dup2} instead, see @ref{dup2}.

@subheading Return Value

If an invalid or unsupported value is passed in @var{cmd}, or @var{fd}
is an invalid file handle, the function returns -1 and sets @code{errno}
to the appropriate value.  Unsupported values of @var{cmd} cause
@code{ENOSYS} to be stored in @code{errno}.  If @var{cmd} is
@code{F_DUPFD}, the function returns the new descriptor or -1 in case of
a failure.

Lock requests which specify the open file's current @code{EOF} position
as the value of @var{l_start} and zero as the @var{l_len} value will
fail, returning -1 with @code{errno} set to @code{EACCES}.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
Contrary to Posix requirement, the handle returned by @code{F_DUPFD} shares the @code{FD_CLOEXEC} flag with @var{fd} (unless they are on different sides of the 20-handle mark), since DOS/Windows only maintain a single set of bits for all the handles associated with the same call to @code{open}.
@end enumerate


@subheading Example

@example
 /* Save the handle in a way that it won't be passed
    to child processes.  */
  int saved_fd = fcntl(fd, F_DUPFD, 20);

 /* Set an advisory lock for the whole file.  */
  struct flock flock;
  int retval, fd;

  flock.l_type = F_RDLCK;
  flock.l_whence = SEEK_SET;
  flock.l_start = flock.l_len = 0;
  errno = 0;
  retval = fcntl(fd, F_SETLK, &flock);

 /* Get the status of the lock we just obtained
    (should return -1 with errno == EACCES).  */
  errno = 0;
  retval = fcntl(fd, F_GETLK, &flock);

 /* Release the lock.  */
  errno = 0;
  flock.l_type = F_UNLCK;
  retval = fcntl(fd, F_SETLK, &flock);

 /* Get the status of the lock we just released
    (should return 0).  */
  errno = 0;
  flock.l_type = F_RDLCK;
  retval = fcntl(fd, F_GETLK, &flock);

 /* Try to set the O_BINARY flag on the open file
    (should return -1 with errno == ENOSYS).  */
  errno = 0;
  retval = fcntl(fd, F_SETFL, O_BINARY);

 /* Set the O_NONBLOCK flag on the open file
    (should return 0).  */
  errno = 0;
  retval = fcntl(fd, F_SETFL, O_NONBLOCK);

 /* Get the flags on the open file
    (always returns 0).  */
  errno = 0;
  retval = fcntl(fd, F_GETFL);

@end example
@c -----------------------------------------------------------------------------
@node fcvt, fcvtbuf, fcntl, Alphabetical List
@unnumberedsec fcvt
@c From file ./compat/stdlib/itoa.txh
@findex fcvt
@subheading Syntax

@example
#include <stdlib.h>

char * fcvt (double value, int ndigits, int *decpt, int *sign)
@end example

@subheading Description

This function converts the @var{value} into a null-terminated string,
and returns a pointer to that string.

@code{fcvt} works exactly like @code{fcvtbuf} (@pxref{fcvtbuf}), except
that it generates the string in an internal static buffer which is
overwritten on each call.

@subheading Return Value

A pointer to the generated string.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable



@c -----------------------------------------------------------------------------
@node fcvtbuf, fdopen, fcvt, Alphabetical List
@unnumberedsec fcvtbuf
@c From file ./compat/stdlib/itoa.txh
@findex fcvtbuf
@subheading Syntax

@example
#include <stdlib.h>

char * fcvtbuf (double value, int ndigits, int *decpt, int *sign,
                char *buf)
@end example

@subheading Description

This function converts its argument @var{value} into a null-terminated
string in @var{buf} with @var{ndigits} digits @emph{to the right} of the
decimal point.  @var{ndigits} can be negative to indicate rounding to
the left of the decimal point.  @var{buf} should have enough space to
hold at least @code{310+max(0,@var{ndigits})} characters.

Note that, unlike @code{ecvtbuf} (@pxref{ecvtbuf}), @code{fcvtbuf} only
counts the digits @emph{to the right} of the decimal point.  Thus, if
@var{value} is 123.45678 and @var{ndigits} is 4, then @code{ecvtbuf}
will produce ``1235'', but @code{fcvtbuf} will produce ``1234568'' (and
@var{*decpt} will be 3 in both cases).

The produced string in @var{buf} does @emph{not} include the decimal
point.  Instead, the position of the decimal point relative to the
beginning of @var{buf} is stored in an integer variable whose address is
passed in @var{decpt}.  Thus, if @var{buf} is returned as ``1234'' and
@var{*decpt} as 1, this corresponds to a value of 1.234; if @var{*decpt}
is -1, this corresponds to a value of 0.01234, etc.

The sign is also not included in @var{buf}'s value.  If @var{value} is
negative, @code{ecvtbuf} puts a nonzero value into the variable whose
address is passed in @var{sign}; otherwise it stores zero in
@var{*sign}.

The least-significant digit in @var{buf} is rounded.

@code{ecvtbuf} produces the string ``NaN'' if @var{value} is a NaN, and
``Inf'' or ``Infinity'' if @var{value} is an infinity (the longer form
is produced when @var{ndigits} is 8 or more).

@subheading Return Value

A pointer to @var{buf}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  #include <stdlib.h>
  #include <stdio.h>
  #include <math.h>

  char vbuf[20];
  int fsign, fdecpt;

  fcvtbuf (M_PI, 5, &fdecpt, &fsign, buf)
  /* This will print " 314159".  */
  printf ("%c%s", fsign ? '-' : ' ', buf);
@end example


@c -----------------------------------------------------------------------------
@node fdopen, feof, fcvtbuf, Alphabetical List
@unnumberedsec fdopen
@c From file ./posix/stdio/fdopen.txh
@findex fdopen
@subheading Syntax

@example
#include <stdio.h>

FILE *fdopen(int fd, const char *mode);
@end example

@subheading Description

This function opens a stream-type file that uses the given @var{fd}
file, which must already be open.  The file is opened with the modes
specified by @var{mode}, which is the same as for @code{fopen}. 
@xref{fopen}.

@subheading Return Value

The newly created @code{FILE *}, or @code{NULL} on error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
FILE *stdprn = fdopen(4, "w");
@end example

@c -----------------------------------------------------------------------------
@node feof, ferror, fdopen, Alphabetical List
@unnumberedsec feof
@c From file ./ansi/stdio/feof.txh
@findex feof
@subheading Syntax

@example
#include <stdio.h>

int feof(FILE *file);
@end example

@subheading Description

This function can be used to indicate if the given @var{file} is at
the end-of-file or not.

@subheading Return Value

Nonzero at end-of-file, zero otherwise.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
while (!feof(stdin))
  gets(line);
@end example

@c -----------------------------------------------------------------------------
@node ferror, fflush, feof, Alphabetical List
@unnumberedsec ferror
@c From file ./ansi/stdio/ferror.txh
@findex ferror
@subheading Syntax

@example
#include <stdio.h>

int ferror(FILE *file);
@end example

@subheading Description

This function can be used to indicate if the given @var{file} has
encountered an error or not.  @xref{clearerr}.

@subheading Return Value

Nonzero for an error, zero otherwise.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
if (ferror(stdin))
  exit(1);
@end example

@c -----------------------------------------------------------------------------
@node fflush, ffs, ferror, Alphabetical List
@unnumberedsec fflush
@c From file ./ansi/stdio/fflush.txh
@findex fflush
@subheading Syntax

@example
#include <stdio.h>

int fflush(FILE *file);
@end example

@subheading Description

If @var{file} is not a @code{NULL} pointer, this function causes any
unwritten buffered data to be written out to the given @var{file}.  This
is useful in cases where the output is line buffered and you want to
write a partial line.

If @var{file} is a @code{NULL} pointer, @code{fflush} writes any
buffered output to all files opened for output.

Note that @code{fflush} has no effect for streams opened for reading
only.  Also note that the operating system can further buffer/cache
writes to disk files; a call to @code{fsync} (@pxref{fsync}) or
@code{sync} (@pxref{sync}) is typically required to actually deliver
data to the file(s).

@subheading Return Value

Zero on success, -1 on error.  When called with a @code{NULL} pointer,
-1 will be returned if an error happened while flushing some of the
streams (but @code{fflush} will still try to flush all the rest before
it returns).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
printf("Enter value : ");
fflush(stdout);
scanf(result);
@end example

@c -----------------------------------------------------------------------------
@node ffs, fgetc, fflush, Alphabetical List
@unnumberedsec ffs
@c From file ./compat/string/ffs.txh
@findex ffs
@subheading Syntax

@example
#include <string.h>

int ffs(int _mask);
@end example

@subheading Description

This function find the first (least significant) bit set in the input
value.

@subheading Return Value

Bit position (1..32) of the least significant set bit, or zero if the
input value is zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
ffs(0) = 0
ffs(1) = 1
ffs(5) = 1
ffs(96) = 6
@end example

@c -----------------------------------------------------------------------------
@node fgetc, fgetgrent, ffs, Alphabetical List
@unnumberedsec fgetc
@c From file ./ansi/stdio/fgetc.txh
@findex fgetc
@subheading Syntax

@example
#include <stdio.h>

int fgetc(FILE *file);
@end example

@subheading Description

Returns the next character in the given @var{file} as an unsigned char. 

@subheading Return Value

The given char (value 0..255) or @code{EOF} at end-of-file.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
int c;
while((c=fgetc(stdin)) != EOF)
  fputc(c, stdout);
@end example

@c -----------------------------------------------------------------------------
@node fgetgrent, fgetpos, fgetc, Alphabetical List
@unnumberedsec fgetgrent
@c From file ./posix/grp/getgrent.txh
@findex fgetgrent
@subheading Syntax

@example
#include <grp.h>

struct group *fgetgrent(FILE *file);
@end example

@subheading Description

This function, in MS-DOS, is exactly the same as @code{getgrent}
(@pxref{getgrent}). 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node fgetpos, fgets, fgetgrent, Alphabetical List
@unnumberedsec fgetpos
@c From file ./ansi/stdio/fgetpos.txh
@findex fgetpos
@subheading Syntax

@example
#include <stdio.h>

int fgetpos(FILE *file, fpos_t *offset);
@end example

@subheading Description

This function records the current file pointer for @var{file}, for
later use by @code{fsetpos}.

@xref{fsetpos}.
@xref{ftell}.

@subheading Return Value

Zero if successful, nonzero if not.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node fgets, File System Extensions, fgetpos, Alphabetical List
@unnumberedsec fgets
@c From file ./ansi/stdio/fgets.txh
@findex fgets
@subheading Syntax

@example
#include <stdio.h>

char *fgets(char *buffer, int maxlength, FILE *file);
@end example

@subheading Description

This function reads as much of a line from a file as possible, stopping
when the buffer is full (@var{maxlength}-1 characters), an end-of-line
is detected, or @code{EOF} or an error is detected.  It then stores a
@code{NULL} to terminate the string.

@subheading Return Value

The address of the buffer is returned on success, if @code{EOF} is
encountered before any characters are stored, or if an error is
detected, @code{NULL} is returned instead. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
char buf[100];
while (fgets(buf, 100, stdin))
  fputs(buf, stdout);
@end example

@c -----------------------------------------------------------------------------
@node File System Extensions, __file_exists, fgets, Alphabetical List
@unnumberedsec File System Extensions
@c From file ./fsext/fsext.txh
@cindex File System Extensions
@cindex FSEXT

@subheading Description

The File System Extensions are a part of the lowest level of I/O
operations in the C runtime library of DJGPP.  These extensions are
provided to allow for cases where Unix uses a file descriptor to
access such items as serial ports, memory, and the network, but DOS
does not.  It allows a set of functions (called an @i{extension}) to
gain control when one of these low-level functions is called on a file
descriptor set up by the extension.

Each extension must provide one or two handler functions.  All handler
functions take the same arguments:

@example
  int function(__FSEXT_Fnumber func_number, int *rv, va_list args);
@end example

The @var{func_number} identifies which function is to be emulated.
The file @code{<sys/fsext.h>} defines the function numbers as follows:

@table @code
@item __FSEXT_nop

A no-op.  This is currently unused by the library functions.

@item __FSEXT_open

An open handler (@pxref{_open}).  This is called just before the library
is about to issue the DOS OpenFile call on behalf of your program.

If @code{_open} was called from the library function @code{open},
then the file name passed to the handler will have either
all its symlink components resolved or will refer to a symlink file
(i.e.: all directory symlinks will be resolved), depending
on whether the @code{O_NOLINK} was passed to @code{open} (@pxref{open}).

Do not use this extension to emulate symlinks.
Use @code{__FSEXT_readlink} handler instead.

@item __FSEXT_creat

A create handler (@pxref{_creat}, and @pxref{_creatnew}).  Called when
a file needs to be created.  Note that the handler should both create
the ``file'' and open it.

If @code{_creat} or @code{_creatnew} were called from
the library functions @code{open} or @code{creat}, then the file name
passed to the handler will have all its symlink components resolved.

@item __FSEXT_read

A read handler (@pxref{_read}).  Called when data should be read from
a ``file''.

@item __FSEXT_write

A write handler (@pxref{write}, and @pxref{_write}).  Called to write data
to a ``file''.  On ``text'' files it receives
the @emph{original} (unconverted) buffer.

@item __FSEXT_ready

A ready handler.  It is called by @code{select} library function
(@pxref{select}) when it needs to know whether a handle used to
reference the ``file'' is ready for reading or writing, or has an error
condition set.  The handler should return an OR'ed bit mask of the
following bits (defined on @code{<sys/fsext.h>}):

@table @code

@item __FSEXT_ready_read

The ``file'' is ready for reading.

@item __FSEXT_ready_write

The ``file'' is ready for writing.

@item __FSEXT_ready_error

The ``file'' has an error condition set.

@end table

@item __FSEXT_close

A close handler (@pxref{_close}).  Called when the ``file'' should be closed.

@item __FSEXT_fcntl

A file fcntl handler (@pxref{fcntl}).

@item __FSEXT_ioctl

A file ioctl handler (@pxref{ioctl (General description)}).

@item __FSEXT_lseek

A file lseek handler (@pxref{lseek}).  Here for backwards
compatibility.  Use @code{__FSEXT_llseek} instead.  If you have a
@code{__FSEXT_llseek} handler you don't need a @code{__FSEXT_lseek}
handler as @code{lseek} calls @code{llseek} internally.

@item __FSEXT_llseek

A file llseek handler (@pxref{llseek}).

@item __FSEXT_link

A file link handler (@pxref{link}).  This is most relevant to file
system extensions that emulate a directory structure.

The source and destination file names are passed to the handler unchanged.

@item __FSEXT_unlink

A file unlink handler (@pxref{remove}, and @pxref{unlink}).  This is most
relevant to file system extensions that emulate a directory structure.

The file name passed to the handler will have all its directory symlinks
resolved, so it may refer to a symlink file.

@item __FSEXT_dup

A file dup handler (@pxref{dup}).  This is called when a new
descriptor is needed to refer to an existing descriptor.

@item __FSEXT_dup2

A file dup2 handler (@pxref{dup2}).  This is called when two different
file descriptors are used to refer to the same open file.

@item __FSEXT_stat

A file lstat handler (@pxref{lstat}).  This extension should provide
information about stated file.  If you provide this hook, function @code{stat}
will be hooked too, as @code{stat} always calls @code{lstat}.

If the handler is called as a result of a @code{stat} call, then
the file name passed to the handler will have all its symlinks resolved,
so it will refer to a ``regular'' file.  If the handler is called
as result of a @code{lstat} call and not a @code{stat} call,
then the file name passed to the handler will have all its directory symlinks
resolved, so it may refer to a symlink file.

@item __FSEXT_fstat

A file fstat handler (@pxref{fstat}).  The extension should fill in
various status information about the emulated file.

@item __FSEXT_readlink

A file readlink handler (@pxref{readlink}).  This extension should be
used to provide support for symlinks in some other than DJGPP format.

The file name passed to the handler will have all its directory symlinks
resolved, so it may refer to a symlink file.

@item __FSEXT_symlink

A file symlink handler (@pxref{symlink}).  This extension should create
symlinks in other than DJGPP symlink file format.

The source and destination file names are passed to the handler unchanged.

@item __FSEXT_chmod

A file chmod handler (@pxref{chmod}).  This is called when
the permissions are to be changed for a file.

The file name passed to the handler will have all its symlinks resolved.

@item __FSEXT_chown

A file chown handler (@pxref{chown}).  This is called when
the ownership is to be changed for a file.

The file name passed to the handler will have all its symlinks resolved.

@item __FSEXT_fchmod

A file fchmod handler (@pxref{fchmod}).  This is called when
the permissions are to be changed for an open file.

@item __FSEXT_fchown

A file fchown handler (@pxref{fchown}).  This is called when
the ownership is to be changed for an open file.

@end table


@var{rv} points to a temporary return value pointer.  If the function is
emulated by the handler, the return value should be stored here, and the
handler should return a nonzero value.  If the handler returns zero, it is
assumed to have not emulated the call, and the regular DOS I/O function
will happen.  The @var{args} represent the arguments passed to the
original function; these point to the actual arguments on the stack, so
the emulation may choose to modify them and return zero to the regular
function, which will then act on the modified arguments.

A normal extension would provide these parts:

@itemize @bullet

@item

Some function to create a connection to the extension.  This may be a
custom function (such as @code{socket} for networking) or an extension
to open (such as @code{/dev/ttyS0} to access the serial port).

@item

Initialization code that adds the open handler, if any.

@item

Overrides for the basic I/O functions, such as @code{read} and
@code{write}.  This is a single function in the extension that uses
the function number parameter to select an extension function.

@item

The core functionality of the extension, if any.

@end itemize

Please note that the special Unix filenames @file{/dev/null} and
@file{/dev/tty} are already mapped to the appropriate DOS names
@file{NUL} and @file{CON}, respectively, so you don't need to write
extensions for these.

Please note that the special Unix filenames @file{/dev/zero} and
@file{/dev/full} can be made available by calling the functions
@code{__install_dev_zero} (@pxref{__install_dev_zero}) and
@code{__install_dev_full} (@pxref{__install_dev_full}) respectively,
so you don't need to write extensions for these.  These are implemented
using File System Extensions.

Programs using the DJGPP debug support functions in @file{libdbg.a} may
have problems using File System Extensions, because the debug support
functions use a File System Extension to track the opening and closing
of files.  Only the @code{__FSEXT_open} and @code{__FSEXT_creat}
calls will be passed to other File System Extensions by
@file{libdbg.a}.  In other words, only fairly trivial File System
Extensions can be used in programs at the same time as the debug
support functions.

@c -----------------------------------------------------------------------------
@node __file_exists, __file_tree_walk, File System Extensions, Alphabetical List
@unnumberedsec __file_exists
@c From file ./dos/dos/fexistp.txh
@findex __file_exists
@subheading Syntax

@example
#include <unistd.h>

int __file_exists(const char *_fn);
@end example

@subheading Description

This function provides a fast way to ask if a given file exists.
Unlike access(), this function does not cause other objects to get
linked in with your program, so is used primarily by the startup code
to keep minimum code size small.

@subheading Return Value

Zero if the file does not exist, nonzero if it does.  Note that this
is the opposite of what access() returns.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example

if (__file_exists(fname))
  process_file(fname);

@end example

@c -----------------------------------------------------------------------------
@node __file_tree_walk, filelength, __file_exists, Alphabetical List
@unnumberedsec __file_tree_walk
@c From file ./dos/dir/ftreewlk.txh
@findex __file_tree_walk
@subheading Syntax

@example
#include <dir.h>

int __file_tree_walk(const char *dir, 
                     int (*func)(const char *path,
                                 const struct ffblk *ff));
@end example

@subheading Description

This function recursively descends the directory hierarchy which starts
with @var{dir}.  For each file in the hierarchy, @code{__file_tree_walk}
calls the user-defined function @var{func} which is passed a pointer to a
@code{NULL}-terminated character array in @var{path} holding the full
pathname of the file, a pointer to a @code{ffblk} structure
(@pxref{findfirst}) @var{ff} with a DOS filesystem information about that
file.

This function always visits a directory before any of its siblings.  The
argument @var{dir} must be a directory, or @code{__file_tree_walk} will fail
and set @code{errno} to @code{ENOTDIR}.  The directory @var{dir} itself is
never passed to @var{func}.

The tree traversal continues until one of the following events:

(1)  The tree is exhausted (i.e., all descendants of @var{dir} are
processed).  In this case, @code{__file_tree_walk} returns 0, meaning a
success.

(2)  An invocation of @var{func} returns a non-zero value.  In this case,
@code{__file_tree_walk} stops the tree traversal and returns whatever
@var{func} returned.

(3)  An error is detected within @code{__file_tree_walk}.  In that case,
@code{ftw} returns -1 and sets @code{errno} (@pxref{errno}) to a suitable
value.

@subheading Return Value

Zero in case the entire tree was successfully traversed, -1 if
@code{__file_tree_walk} detected some error during its operation, or any
other non-zero value which was returned by the user-defined function
@var{func}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
#include <stdlib.h>

int
ff_walker(const char *path, const struct ffblk *ff)
@{
  printf("%s:\t%lu\t", path, ff->ff_fsize);
  if (ff->ff_attrib & 1)
    printf("R");
  if (ff->ff_attrib & 2)
    printf("H");
  if (ff->ff_attrib & 4)
    printf("S");
  if (ff->ff_attrib & 8)
    printf("V");
  if (ff->ff_attrib & 0x10)
    printf("D");
  if (ff->ff_attrib & 0x20)
    printf("A");
  printf("\n");

  if (strcmp(ff->ff_name, "XXXXX") == 0)
    return 42;
  return 0;
@}

int
main(int argc, char *argv[])
@{
  if (argc > 1)
    @{
      char msg[80];

      sprintf(msg, "__file_tree_walk: %d",
                   __file_tree_walk(argv[1], ff_walker));
      if (errno)
        perror(msg);
      else
        puts(msg);
    @}
  else
    printf("Usage: %s dir\n", argv[0]);

  return 0;
@}
@end example
@c -----------------------------------------------------------------------------
@node filelength, fileno, __file_tree_walk, Alphabetical List
@unnumberedsec filelength
@c From file ./posix/sys/stat/filelen.txh
@findex filelength
@subheading Syntax

@example
#include <io.h>

long filelength(int fhandle);
@end example

@subheading Description

This function returns the size, in bytes, of a file whose handle is
specified in the argument @var{fhandle}.  To get the handle of a file
opened by @code{fopen} (@pxref{fopen}) or @code{freopen} (@pxref{freopen}),
you can use @code{fileno} macro (@pxref{fileno}).

@subheading Return Value

The size of the file in bytes, or (if any error occurred) -1L and
@code{errno} set to a value describing the cause of the failure.  If the
file's length is larger than a 32-bit @code{unsigned int} can hold,
@code{errno} will be set to @code{EOVERFLOW}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  printf("Size of file to which STDIN is redirected is %ld\n", 
          filelength(0));
@end example

@c -----------------------------------------------------------------------------
@node fileno, findfirst, filelength, Alphabetical List
@unnumberedsec fileno
@c From file ./posix/stdio/fileno.txh
@findex fileno
@subheading Syntax

@example
#include <stdio.h>

int fileno(FILE *file);
@end example

@subheading Description

This function returns the raw file descriptor number that @var{file}
uses for I/O. 

@subheading Return Value

The file descriptor number.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node findfirst, findnext, fileno, Alphabetical List
@unnumberedsec findfirst
@c From file ./dos/dir/findfirs.txh
@findex findfirst
@tindex ffblk@r{ structure}
@subheading Syntax

@example
#include <dir.h>

int findfirst(const char *pathname, struct ffblk *ffblk, int attrib);
@end example

@subheading Description

This function and the related @code{findnext} (@pxref{findnext}) are used
to scan directories for the list of files therein.  The @var{pathname}
is a wildcard that specifies the directory and files to search for (such
as @code{subdir/*.c}), @var{ffblk} is a structure to hold the results and
state of the search, and @var{attrib} is a combination of the following:

@table @code

@item FA_RDONLY

Include read-only files in the search (Ignored.)

@item FA_HIDDEN

Include hidden files in the search

@item FA_SYSTEM

Include system files in the search

@item FA_LABEL

Include the volume label in the search

@item FA_DIREC

Include subdirectories in the search

@item FA_ARCH

Include modified files in the search (Ignored.)

@end table

If a file has flag bits that are not specified in the @var{attrib}
parameter, the file will be excluded from the results.  Thus, if you
specified @code{FA_DIREC} and @code{FA_LABEL}, subdirectories and the
volume label will be included in the results.  Hidden and system files
will be excluded.

Since @code{findfirst} calls DOS function 4eh, it is not possible to
exclude read-only files or archive files from the results.  Even if
the FA_ARCH and FA_RDONLY bits are not specified in the attrib
parameter, the results will include any read-only and archive files in
the directory searched.   

This function supports long file names.

The results of the search are stored in @var{ffblk}, which is extended
when the LFN API (@pxref{_use_lfn, LFN}) is supported.  Fields marked
LFN are only valid if the @code{lfn_magic} member is set to "LFN32".

@example
struct ffblk @{
  char lfn_magic[6];	    /* LFN: the magic "LFN32" signature */
  short lfn_handle;	    /* LFN: the handle used by findfirst/findnext */
  unsigned short lfn_ctime; /* LFN: file creation time */
  unsigned short lfn_cdate; /* LFN: file creation date */
  unsigned short lfn_atime; /* LFN: file last access time (usually 0) */
  unsigned short lfn_adate; /* LFN: file last access date */
  char ff_reserved[5];      /* used to hold the state of the search */
  unsigned char ff_attrib;  /* actual attributes of the file found */
  unsigned short ff_ftime;  /* hours:5, minutes:6, (seconds/2):5 */
  unsigned short ff_fdate;  /* (year-1980):7, month:4, day:5 */
  unsigned long ff_fsize;   /* size of file */
  char ff_name[260];        /* name of file as ASCIIZ string */
@}
@end example

@subheading Return Value

Zero if a match is found, nonzero if none found.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
struct ffblk f;
int done = findfirst("*.exe", &f, FA_HIDDEN | FA_SYSTEM);
while (!done)
@{
  printf("%10u %2u:%02u:%02u %2u/%02u/%4u %s\n",
    f.ff_fsize,
    (f.ff_ftime >> 11) & 0x1f,
    (f.ff_ftime >>  5) & 0x3f,
    (f.ff_ftime & 0x1f) * 2,
    (f.ff_fdate >>  5) & 0x0f,
    (f.ff_fdate & 0x1f),
    ((f.ff_fdate >> 9) & 0x7f) + 1980,
    f.ff_name);
  done = findnext(&f);
@}
@end example

@c -----------------------------------------------------------------------------
@node findnext, _fixpath, findfirst, Alphabetical List
@unnumberedsec findnext
@c From file ./dos/dir/findnext.txh
@findex findnext
@subheading Syntax

@example
#include <dir.h>

int findnext(struct ffblk *ffblk);
@end example

@subheading Description

This finds the next file in the search started by @code{findfirst}.
@xref{findfirst}.

@subheading Return Value

Zero if there was a match, else nonzero.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _fixpath, flock, findnext, Alphabetical List
@unnumberedsec _fixpath
@c From file ./posix/sys/stat/fixpath.txh
@findex _fixpath
@subheading Syntax

@example
#include <sys/stat.h>

void _fixpath(const char *in_path, char *out_path);
@end example

@subheading Description

This function canonicalizes the input path @var{in_path} and stores the
result in the buffer pointed to by @var{out_path}.

The path is fixed by removing consecutive and trailing slashes, making
the path absolute if it's relative by prepending the current drive
letter and working directory, removing "." components, collapsing
".." components, adding a drive specifier if needed, and converting all
slashes to '/'.  DOS-style 8+3 names of directories which are part of
the pathname, as well as its final filename part, are returned
lower-cased in @var{out_path}, but long filenames are left intact.
@xref{_preserve_fncase}, for more details on letter-case conversions in
filenames.

Since the returned path name can be longer than the original one, the
caller should ensure there is enough space in the buffer pointed to by
@var{out_path}.  Using ANSI-standard constant @code{FILENAME_MAX}
(defined on @file{stdio.h}) or Posix-standard constant @code{PATH_MAX}
(defined on @file{limits.h}) is recommended.

@subheading Return Value

None.  If the length of the returned path name exceeds @code{FILENAME_MAX},
@code{errno} is set to @code{ENAMETOOLONG}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char oldpath[100], newpath[FILENAME_MAX];
scanf("%s", oldpath);
_fixpath(oldpath, newpath);
printf("that really is %s\n", newpath);
@end example

@c -----------------------------------------------------------------------------
@node flock, floor, _fixpath, Alphabetical List
@unnumberedsec flock
@c From file ./posix/sys/file/flock.txh
@findex flock
@subheading Syntax

@example
#include <sys/file.h>

int flock (int _fildes, int _op);
@end example

@subheading Description

Apply or remove an advisory lock on an open file.  The file is specified
by file handle @var{_fildes}.  Valid operations are given below:

@table @code
@item LOCK_SH
Shared lock.  More than one process may hold a shared lock for a given
file at a given time.  However, all locks on DOS/Windows 9X are
exclusive locks, so @code{LOCK_SH} requests are treated as if they were
@code{LOCK_EX} requests.

@item LOCK_EX
Exclusive lock.  Only one process may hold an exclusive lock for a given
file at a given time.

@item LOCK_UN
Unlock the file.

@item LOCK_NB
Don't block when locking.  May be specified (by or'ing) along with one
of the other operations.
@end table

On other systems, a single file may not simultaneously have both shared
and exclusive locks.  However, on DOS/Windws 9X, all locks are exclusive
locks, so this rule is not true for DOS/Windows 9X.

A file is locked, not the file descriptor.  So, @samp{dup (2);} does not
create multiple instances of a lock.

Dos/Windows 9X do not support shared locks, but the underlying
implementation (which uses the @code{F_SETLK} (non-blocking) or
@code{F_SETLKW} (blocking) commands to @code{fcntl}, @pxref{fcntl})
translates all shared lock request into exclusive lock requests.  Thus,
requests for shared locks will be treated as if exclusive locks were
requested, and only one lock will ever be permitted at any one time on
any specified region of the file.

It is therefore wise to code @code{flock} by @code{or}ing @code{LOCK_NB} with
all lock requests, whether shared or exclusive, and to test the return
value to determine if the lock was obtained or not.  Using
@code{LOCK_NB} will cause the implementation to use @code{F_SETLK}
instead of @code{F_SETLKW}, which will return an error if the lock
cannot be obtained.

@subheading Return Value

On success, zero is returned.  On error, -1 is returned, and
@code{errno} is set appropriately.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
4.4BSD (the flock (2) call first appeared in 4.2BSD).
@end enumerate

@subheading Example

@example
 /* Request a shared lock on file handle fd */
  errno = 0;
  retval = flock(fd, LOCK_SH);

 /* Request a non-blocking shared lock on file handle fd */
  errno = 0;
  retval = flock(fd, LOCK_SH | LOCK_NB);

 /* Request an exclusive lock on file handle fd */
  errno = 0;
  retval = flock(fd, LOCK_EX);

 /* Request a non-blocking exclusive lock on file handle fd */
  errno = 0;
  retval = flock(fd, LOCK_EX | LOCK_NB);

 /* Release a lock on file handle fd */
  errno = 0;
  retval = flock(fd, LOCK_UN);
@end example
@c -----------------------------------------------------------------------------
@node floor, _flush_disk_cache, flock, Alphabetical List
@unnumberedsec floor
@c From file ./ansi/math/floor.txh
@findex floor
@subheading Syntax

@example
#include <math.h>

double floor(double x);
@end example

@subheading Description

This function computes the largest integer not greater than @var{x}.

@subheading Return Value

The largest integer value less than or equal to @var{x}.  Infinities and
@code{NaN}s are returned unchanged.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node _flush_disk_cache, fmod, floor, Alphabetical List
@unnumberedsec _flush_disk_cache
@c From file ./dos/io/flushdc.txh
@findex _flush_disk_cache
@subheading Syntax

@example
#include <io.h>

void _flush_disk_cache (void);
@end example

@subheading Description

Attempts to update the disk with the data cached in the write-behind
disk caches (such as @code{SmartDrv} and the built-in Windows 95 disk
cache).

Note that this does @strong{not} flush the DOS buffers.  You need to
call @code{fsync} (@pxref{fsync}) or @code{close} (@pxref{close}) to
force DOS to commit the file data to the disk; @code{sync}
(@pxref{sync}) does that for all open files, and also calls
@code{_flush_disk_cache}.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  /* Make sure all cached data for a handle FD is actually
     written to disk.  */
  fsync (fd);
  _flush_disk_cache ();
@end example
@c -----------------------------------------------------------------------------
@node fmod, _fmode, _flush_disk_cache, Alphabetical List
@unnumberedsec fmod
@c From file ./ansi/math/fmod.txh
@findex fmod
@subheading Syntax

@example
#include <math.h>

double fmod(double x, double y);
@end example

@subheading Description

This function computes the remainder of @code{@var{x}/@var{y}}, which is
@math{@var{x} - i@var{y}} for some integer i such that
@math{i@var{y} < @var{x} < (i+1)@var{y}}.

@subheading Return Value

The remainder of @var{x}/@var{y}.  If @var{x} is @code{Inf} or
@code{NaN}, the return value is @code{NaN} and @code{errno} is set to
@code{EDOM}.  If @var{y} is zero, the return value is zero (but
@code{errno} is not changed).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node _fmode, fnmatch, fmod, Alphabetical List
@unnumberedsec _fmode
@c From file ./dos/io/fmode.txh
@vindex _fmode
@subheading Syntax

@example
#include <fcntl.h>

extern int _fmode;
@end example

@subheading Description

This variable may be set to @code{O_TEXT} or @code{O_BINARY} to specify
the mode that newly opened files should be opened in if the open call
did not specify.  @xref{open}. @xref{fopen}.

The default value is @code{O_TEXT}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
_fmode = O_BINARY;
@end example

@c -----------------------------------------------------------------------------
@node fnmatch, fnmerge, _fmode, Alphabetical List
@unnumberedsec fnmatch
@c From file ./posix/fnmatch/fnmatch.txh
@findex fnmatch
@subheading Syntax

@example
#include <fnmatch.h>

int fnmatch(const char *pattern, const char *string, int flags);
@end example

@subheading Description

This function indicates if @var{string} matches the @var{pattern}.  The
@var{pattern} may include the following special characters:

@table @code

@item *

Matches zero of more characters.

@item ?

Matches exactly one character.

@item [...]

Matches one character if it's in a range of characters.  If the first
character is @samp{!}, matches if the character is not in the range. 
Between the brackets, the range is specified by listing the characters
that are in the range, or two characters separated by @samp{-} to
indicate all characters in that range.  For example, @samp{[a-d]}
matches @samp{a}, @samp{b}, @samp{c}, or @samp{d}.  If you want to
include the literal @samp{-} in the range, make it the first character,
like in @samp{[-afz]}.

@item \

Causes the next character to not be treated as a wildcard.  For example,
@samp{\*} matches an asterisk.  This feature is not available if
@var{flags} includes @code{FNM_NOESCAPE}, in which case @samp{\} is
treated as a directory separator.

@end table

The value of @var{flags} is a combination of zero of more of the
following:

@table @code

@item FNM_PATHNAME

This means that the @var{string} should be treated as a pathname, in
that the slash characters @samp{/} and @samp{\} in @var{string} never
match any of the wildcards in @var{pattern}.

@item FNM_NOESCAPE

If this flag is @strong{not} set, the backslash @samp{\} may be used in
@var{pattern} for quoting special characters.  If this flag @strong{is}
set, @samp{\} is treated as a directory separator.

@item FNM_NOCASE

If this flag is set, @code{fnmatch} matches characters
case-insensitively, including in character ranges like @code{[a-f]}.
Note that the case-folding is done by calling @code{toupper}
(@pxref{toupper}), and thus might be sensitive to the current locale.

@item FNM_PERIOD

This flag is accepted and ignored in the current implementation.  (This
is the right thing to do on non-LFN platforms, where leading dots in
file names are forbidden.)

In the Posix specification, if this flag is set, leading dots in file
names will not match any wildcards.  If @code{FNM_PATHNAME} is set, a
dot after a slash also doesn't match any wildcards.

@end table

The DJGPP implementation treats forward slashes and backslashes as equal
when @code{FNM_NOESCAPE} is set, since on DOS/Windows these two
characters are both used as directory separators in file names.

@subheading Return Value

Zero if the string matches, @code{FNM_NOMATCH} if it does not.  Posix
defines an additional @code{FNM_ERROR} code that's returned in case of
an error, but the current implementation never returns it.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
The equal handling of @samp{\} and @samp{/} is DJGPP-specific.
@end enumerate

@subheading Example

@example
if (fnmatch("*.[ch]", filename, FNM_PATHNAME|FNM_NOCASE))
  do_source_file(filename);
@end example

@c -----------------------------------------------------------------------------
@node fnmerge, fnsplit, fnmatch, Alphabetical List
@unnumberedsec fnmerge
@c From file ./dos/dir/fnsplit.txh
@findex fnmerge
@subheading Syntax

@example
#include <dir.h>

void fnmerge (char *path, const char *drive, const char *dir,
		const char *name, const char *ext);
@end example

@subheading Description

This function constructs a file @var{path} from its components
@var{drive}, @var{dir}, @var{name}, and @var{ext}.  If any of these is a
@code{NULL} pointer, it won't be used.  Usually, the @var{drive} string
should include the trailing colon @code{`:'}, the @var{dir} string should
include the trailing slash @code{`/'} or backslash @code{`\'}, and the
@var{ext} string should include the leading dot @code{`.'}.  However, if
any of these isn't present, @code{fnmerge} will add them.

@xref{fnsplit}.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char buf[MAXPATH];
fnmerge(buf, "d:", "/foo/", "data", ".txt");
@end example

@c -----------------------------------------------------------------------------
@node fnsplit, fopen, fnmerge, Alphabetical List
@unnumberedsec fnsplit
@c From file ./dos/dir/fnsplit.txh
@findex fnsplit
@subheading Syntax

@example
#include <dir.h>

int fnsplit (const char *path, char *drive, char *dir, 
		char *name, char *ext);
@end example

@subheading Description

This function decomposes a @var{path} into its components.  It is smart
enough to know that @code{.} and @code{..} are directories, and that
file names with a leading dot, like @file{.emacs}, are not all extensions.

The @var{drive}, @var{dir}, @var{name} and @var{ext} arguments should
all be passed, but some or even all of them might be @code{NULL} pointers.
Those of them which are non-@code{NULL} should point to buffers which have
enough room for the strings they would hold.  The constants @code{MAXDRIVE},
@code{MAXDIR}, @code{MAXFILE} and @code{MAXEXT}, defined on dir.h, define
the maximum length of these buffers.

@xref{fnmerge}.

@subheading Return Value

A flag that indicates which components were found:

@table @code

@item DRIVE

The drive letter was found.

@item DIRECTORY

A directory or subdirectories was found.

@item FILENAME

A filename was found.

@item EXTENSION

An extension was found.

@item WILDCARDS

The path included @code{*} or @code{?}.

@end table

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char d[MAXDRIVE], p[MAXDIR], f[MAXFILE], e[MAXEXT];
int which = fnsplit("d:/djgpp/bin/gcc.exe", d, p, f, e);
d = "d:"
p = "/djgpp/bin/"
f = "gcc"
e = ".exe"
@end example

@c -----------------------------------------------------------------------------
@node fopen, fork, fnsplit, Alphabetical List
@unnumberedsec fopen
@c From file ./ansi/stdio/fopen.txh
@findex fopen
@subheading Syntax

@example
#include <stdio.h>

FILE *fopen(const char *filename, const char *mode);
@end example

@subheading Description

This function opens a stream corresponding to the named @var{filename}
with the given @var{mode}.  The mode can be one of the following:

@table @code

@item r

Open an existing file for reading.

@item w

Create a new file (or truncate an existing file) and open it for
writing. 

@item a

Open an existing file (or create a new one) for writing.  The file
pointer is positioned to the end of the file before every write. 

@end table

Followed by any of these characters:

@table @code

@item b

Force the file to be open in binary mode instead of the default mode.

When called to open the console in binary mode, @code{fopen} will
disable the generation of @code{SIGINT} when you press @kbd{Ctrl-C}
(@kbd{Ctrl-Break} will still cause @code{SIGINT}), because many programs
that use binary reads from the console will also want to get the
@samp{^C} characters.  You can use the @code{__djgpp_set_ctrl_c} library
function (@pxref{__djgpp_set_ctrl_c}) if you want @kbd{Ctrl-C} to
generate interrupts while console is read in binary mode.

@item t

Force the file to be open in text mode instead of the default mode.

@item +

Open the file as with @code{O_RDWR} so that both reads and writes
can be done to the same file.

@end table

If the file is open for both reading and writing, you must call
@code{fflush}, @code{fseek}, or @code{rewind} before switching from read
to write or from write to read. 

The open file is set to line buffered if the underlying object is a
device (stdin, stdout, etc), or is fully buffered if the underlying
object is a disk file (data.c, etc).

If @code{b} or @code{t} is not specified in @var{mode}, the file type is
chosen by the value of @code{fmode} (@pxref{_fmode}). 

You can open directories using @code{fopen}, but there is limited
support for stream file operations on directories.  In particular,
they cannot be read from or written to.

If you need to specify the DOS share flags use the @code{__djgpp_share_flags}.
@xref{__djgpp_share_flags}.

@subheading Return Value

A pointer to the @code{FILE} object, or @code{NULL} if there was an
error. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
FILE *f = fopen("foo", "rb+"); /* open existing file for read/write,
                                * binary mode */
@end example

@c -----------------------------------------------------------------------------
@node fork, fpathconf, fopen, Alphabetical List
@unnumberedsec fork
@c From file ./posix/unistd/fork.txh
@findex fork
@subheading Syntax

@example
#include <unistd.h>

pid_t fork(void);
@end example

@subheading Description

This function always returns -1 and sets @code{errno} to ENOMEM, as
MS-DOS does not support multiple processes.  It exists only to assist
in porting Unix programs.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node fpathconf, fpclassify, fork, Alphabetical List
@unnumberedsec fpathconf
@c From file ./posix/unistd/pathconf.txh
@findex fpathconf
@subheading Syntax

@example
#include <unistd.h>

long fpathconf(int fd, int name);
@end example

@subheading Description

Returns configuration information on the filesystem that the open file
resides on.  @xref{pathconf}.  If the filesystem cannot be determined
from the file handle @var{fd} (e.g., for character devices),
@code{fpathconf} will return the info for the current drive.

@subheading Return Value

The configuration value; for details, see @ref{pathconf}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node fpclassify, __fpclassifyd, fpathconf, Alphabetical List
@unnumberedsec fpclassify
@c From file ./c99/math/fpclass.txh
@findex fpclassify
@subheading Syntax

@example
#include <math.h>
@end example

@subheading Description

The macro @code{fpclassify} returns the kind of the floating point
value supplied.

@subheading Return Value

@code{FP_INFINITE}, @code{FP_NAN}, @code{FP_NORMAL},
@code{FP_SUBNORMAL}, @code{FP_ZERO} or @code{FP_UNNORMAL}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@end multitable


@subheading Example

@example
float f = 1;
double d = INFINITY;
long double ld = NAN;

if( fpclassify(f) != FP_NORMAL )
@{
  printf("Something is wrong with the implementation!\n");
@}
if( fpclassify(d) != FP_INFINITE )
@{
  printf("Something is wrong with the implementation!\n");
@}
if( fpclassify(ld) != FP_NAN )
@{
  printf("Something is wrong with the implementation!\n");
@}

@end example

@c -----------------------------------------------------------------------------
@node __fpclassifyd, __fpclassifyf, fpclassify, Alphabetical List
@unnumberedsec __fpclassifyd
@c From file ./c99/math/fpclassd.txh
@findex __fpclassifyd
@subheading Syntax

@example
#include <math.h>

int __fpclassifyd(double);
@end example

@subheading Description

Returns the kind of the floating point value supplied. You should use
the type generic macro @code{fpclassify} (@pxref{fpclassify}) instead
of this function.

@subheading Return Value

@code{FP_INFINITE}, @code{FP_NAN}, @code{FP_NORMAL},
@code{FP_SUBNORMAL} or @code{FP_ZERO}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@end multitable


@subheading Example

@example
if( __fpclassifyd(0.0) != FP_ZERO )
@{
  printf("Something is wrong with the implementation!\n");
@}

@end example

@c -----------------------------------------------------------------------------
@node __fpclassifyf, __fpclassifyld, __fpclassifyd, Alphabetical List
@unnumberedsec __fpclassifyf
@c From file ./c99/math/fpclassf.txh
@findex __fpclassifyf
@subheading Syntax

@example
#include <math.h>

int __fpclassifyf(float);
@end example

@subheading Description

Returns the kind of the floating point value supplied. You should use
the type generic macro @code{fpclassify} (@pxref{fpclassify}) instead
of this function.

@subheading Return Value

@code{FP_INFINITE}, @code{FP_NAN}, @code{FP_NORMAL},
@code{FP_SUBNORMAL} or @code{FP_ZERO}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@end multitable


@subheading Example

@example
if( __fpclassifyf(0.0F) != FP_ZERO )
@{
  printf("Something is wrong with the implementation!\n");
@}

@end example

@c -----------------------------------------------------------------------------
@node __fpclassifyld, _fpreset, __fpclassifyf, Alphabetical List
@unnumberedsec __fpclassifyld
@c From file ./c99/math/fpclassl.txh
@findex __fpclassifyld
@subheading Syntax

@example
#include <math.h>

int __fpclassifyld(long double);
@end example

@subheading Description

Returns the kind of the floating point value supplied. You should use
the type generic macro @code{fpclassify} (@pxref{fpclassify}) instead
of this function.

@subheading Return Value

@code{FP_INFINITE}, @code{FP_NAN}, @code{FP_NORMAL},
@code{FP_SUBNORMAL}, @code{FP_ZERO} or @code{FP_UNNORMAL}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@end multitable


@subheading Example

@example
if( __fpclassifyld(0.0L) != FP_ZERO )
@{
  printf("Something is wrong with the implementation!\n");
@}

@end example

@c -----------------------------------------------------------------------------
@node _fpreset, fprintf, __fpclassifyld, Alphabetical List
@unnumberedsec _fpreset
@c From file ./pc_hw/fpu/fpreset.txh
@findex _fpreset
@subheading Syntax

@example
#include <float.h>

void _fpreset(void);
@end example

@subheading Description

Resets the FPU completely.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node fprintf, fpurge, _fpreset, Alphabetical List
@unnumberedsec fprintf
@c From file ./ansi/stdio/fprintf.txh
@findex fprintf
@subheading Syntax

@example
#include <stdio.h>

int fprintf(FILE *file, const char *format, @dots{});
@end example

@subheading Description

Prints formatted output to the named file.  @xref{printf}.

@subheading Return Value

The number of characters written.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node fpurge, fputc, fprintf, Alphabetical List
@unnumberedsec fpurge
@c From file ./compat/v1/fpurge.txh
@findex fpurge
@subheading Syntax

@example
#include <stdio.h>

int fpurge(FILE *file);
@end example

@subheading Description

If @var{file} designates a buffered stream open for writing or for both
reading and writing, this function purges the stream's buffer without
writing it to disk.  Otherwise, it does nothing (so it has no effect on
read-only streams such as @code{stdin}).

@subheading Return Value

Zero on success, -1 on failure.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node fputc, fputs, fpurge, Alphabetical List
@unnumberedsec fputc
@c From file ./ansi/stdio/fputc.txh
@findex fputc
@subheading Syntax

@example
#include <stdio.h>

int fputc(int character, FILE *file);
@end example

@subheading Description

This function writes the given @var{character} to the given @code{file}.

@subheading Return Value

The given character [0..255] or @code{EOF}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
fputc('\n', stdout);
@end example

@c -----------------------------------------------------------------------------
@node fputs, fread, fputc, Alphabetical List
@unnumberedsec fputs
@c From file ./ansi/stdio/fputs.txh
@findex fputs
@subheading Syntax

@example
#include <stdio.h>

int fputs(const char *string, FILE *file);
@end example

@subheading Description

This function copies all the characters of @var{string} (except the trailing
@code{NULL}) to the given @var{file}.

@subheading Return Value

A nonnegative number on success, @code{EOF} on error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
fputs("Hello\n", stdout);
@end example

@c -----------------------------------------------------------------------------
@node fread, free, fputs, Alphabetical List
@unnumberedsec fread
@c From file ./ansi/stdio/fread.txh
@findex fread
@subheading Syntax

@example
#include <stdio.h>

size_t fread(void *buffer, size_t size, size_t number, FILE *file);
@end example

@subheading Description

This function reads @var{size}*@var{number} characters from @var{file}
to @var{buffer}. 

@subheading Return Value

The number of items of size @var{size} read, or less if there was an
error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
int foo[10];
fread(foo, sizeof(int), 10, stdin);
@end example

@c -----------------------------------------------------------------------------
@node free, freopen, fread, Alphabetical List
@unnumberedsec free
@c From file ./ansi/stdlib/nmalloc.txh
@subheading Syntax

@example
#include <stdlib.h>

void free(void *ptr);
@end example

@subheading Description

Returns the allocated memory to the heap (@pxref{malloc}).  If
the @var{ptr} is @code{NULL}, @code{free} does nothing.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
char *q = malloc(20);
free(q);
@end example


@c -----------------------------------------------------------------------------
@node freopen, frexp, free, Alphabetical List
@unnumberedsec freopen
@c From file ./ansi/stdio/freopen.txh
@findex freopen
@subheading Syntax

@example
#include <stdio.h>

FILE *freopen(const char *filename, const char *mode, FILE *file);
@end example

@subheading Description

This function closes @var{file} if it was open, then opens a new
file like @code{fopen(filename, mode)} (@pxref{fopen})
but it reuses @var{file}.

This is useful to, for example, associate @code{stdout} with a new file. 

@subheading Return Value

The new file, or @code{NULL} on error. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
freopen("/tmp/stdout.dat", "wb", stdout);
@end example

@c -----------------------------------------------------------------------------
@node frexp, fscanf, freopen, Alphabetical List
@unnumberedsec frexp
@c From file ./ansi/math/frexp.txh
@findex frexp
@subheading Syntax

@example
#include <math.h>

double frexp(double x, int *pexp);
@end example

@subheading Description

This function separates the given value @var{x} into a mantissa m in the
range @code{[0.5,1)} and an exponent e, such that @math{m*2^e = @var{x}}.
It returns the value of the mantissa and stores the integer exponent in
@var{*pexp}.

@subheading Return Value

The mantissa.  If the value of @var{x} is @code{NaN} or @code{Inf}, the
return value is @code{NaN}, zero is stored in @code{*pexp}, and
@code{errno} is set to @code{EDOM}.  If @var{x} is zero, @var{*pexp} and
the return value are also both zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node fscanf, fseek, frexp, Alphabetical List
@unnumberedsec fscanf
@c From file ./ansi/stdio/fscanf.txh
@findex fscanf
@subheading Syntax

@example
#include <stdio.h>

int fscanf(FILE *file, const char *format, @dots{});
@end example

@subheading Description

This function scans formatted text from @var{file} and stores it in the
variables pointed to by the arguments.  @xref{scanf}.

@subheading Return Value

The number of items successfully scanned.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node fseek, fseeko, fscanf, Alphabetical List
@unnumberedsec fseek
@c From file ./ansi/stdio/fseek.txh
@findex fseek
@subheading Syntax

@example
#include <stdio.h>

int fseek(FILE *file, long offset, int mode);
@end example

@subheading Description

This function moves the file pointer for @var{file} according to
@var{mode}:

@table @code

@item SEEK_SET

The file pointer is moved to the offset specified.

@item SEEK_CUR

The file pointer is moved relative to its current position.

@item SEEK_END

The file pointer is moved to a position @var{offset} bytes from the end
of the file.  The offset is usually nonpositive in this case. 

@end table

@emph{Warning!} The ANSI standard only allows values of zero for
@var{offset} when @var{mode} is not @code{SEEK_SET} and the file has
been opened as a text file.  Although this restriction is not enforced,
beware that there is not a one-to-one correspondence between file
characters and text characters under MS-DOS, so some @code{fseek}
operations may not do exactly what you expect.

Also, since @code{lseek} under DOS does not return an error indication
when you try to move the file pointer before the beginning of the file,
neither will @code{fseek}.  Portable programs should call @code{ftell}
after @code{fseek} to get the actual position of the file pointer.

Note that DOS does not mind if you seek before the beginning of the
file, like seeking from the end of the file by more than the file's
size.  Therefore, @code{lseek} will not return with an error in such
cases either.

@subheading Return Value

Zero if successful, nonzero if not. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
fseek(stdin, 12, SEEK_CUR); /* skip 12 bytes */
@end example

@c -----------------------------------------------------------------------------
@node fseeko, fsetpos, fseek, Alphabetical List
@unnumberedsec fseeko
@c From file ./compat/stdio/fseeko.txh
@findex fseeko
@subheading Syntax

@example
#include <stdio.h>

int fseeko(FILE *file, off_t offset, int mode);
@end example

@subheading Description

@code{fseeko} is a wrapper function of @code{fseek} (@pxref{fseek}).
So it is identical to @code{fseek}, except that the offset argument
of @code{fseeko} is of type @code{off_t} instead of @code{long}.


This function moves the file pointer for @var{file} according to
@var{mode}:

@table @code

@item SEEK_SET

The file pointer is moved to the offset specified.

@item SEEK_CUR

The file pointer is moved relative to its current position.

@item SEEK_END

The file pointer is moved to a position @var{offset} bytes from the end
of the file.  The offset is usually nonpositive in this case.

@end table

@emph{Warning!} The ANSI standard only allows values of zero for
@var{offset} when @var{mode} is not @code{SEEK_SET} and the file has
been opened as a text file.  Although this restriction is not enforced,
beware that there is not a one-to-one correspondence between file
characters and text characters under MS-DOS, so some @code{fseeko}
operations may not do exactly what you expect.

Also, since @code{lseek} under DOS does not return an error indication
when you try to move the file pointer before the beginning of the file,
neither will @code{fseeko}.  Portable programs should call @code{ftello}
after @code{fseeko} to get the actual position of the file pointer.

Note that DOS does not mind if you seek before the beginning of the
file, like seeking from the end of the file by more than the file's
size.  Therefore, @code{lseek} will not return with an error in such
cases either.

@subheading Return Value

Zero if successful, nonzero if not. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
fseeko(stdin, 12, SEEK_CUR); /* skip 12 bytes */
@end example

@c -----------------------------------------------------------------------------
@node fsetpos, __FSEXT_add_open_handler, fseeko, Alphabetical List
@unnumberedsec fsetpos
@c From file ./ansi/stdio/fsetpos.txh
@findex fsetpos
@subheading Syntax

@example
#include <stdio.h>

int fsetpos(FILE *file, const fpos_t *offset);
@end example

@subheading Description

This function moves the file pointer for @var{file} to position
@var{offset}, as recorded by @code{fgetpos}.

@xref{fgetpos}.
@xref{fseek}.

@subheading Return Value

Zero if successful, nonzero if not.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node __FSEXT_add_open_handler, __FSEXT_alloc_fd, fsetpos, Alphabetical List
@unnumberedsec __FSEXT_add_open_handler
@c From file ./fsext/fse_open.txh
@findex __FSEXT_add_open_handler
@subheading Syntax

@example
#include <sys/fsext.h>

int __FSEXT_add_open_handler(__FSEXT_Function *_function);
@end example

@subheading Description

This function is part of the @ref{File System Extensions}.  It is used
to add a handler for functions that do not get passed descriptors,
such as @code{_open} and @code{_creat}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
static int
_my_handler(__FSEXT_Fnumber n, int *rv, va_list args)
@{
  . . .
@}

int main()
@{
  __FSEXT_add_open_handler(_my_handler);
@}

@end example

@c -----------------------------------------------------------------------------
@node __FSEXT_alloc_fd, __FSEXT_call_open_handlers, __FSEXT_add_open_handler, Alphabetical List
@unnumberedsec __FSEXT_alloc_fd
@c From file ./fsext/fsext.txh
@findex __FSEXT_alloc_fd
@subheading Syntax

@example
#include <sys/fsext.h>

int __FSEXT_alloc_fd(__FSEXT_Function *_function);
@end example

@subheading Description

This function is part of the @ref{File System Extensions}.  It is used
by extensions that fully emulate the I/O functions, and thus don't
have a corresponding DOS file handle.  Upon the first call, this
function opens DOS's @samp{NUL} device, so as to allocate a handle that
DOS won't then reuse.  Upon subsequent calls, that handle is duplicated
by calling the DOS @code{dup} function; this makes all of the handles
use a single entry in the System File Table, and thus be independent of
what the @samp{FILES=} parameter of @file{CONFIG.SYS} says.
@code{__FSEXT_alloc_fd} also assigns the handler function for the handle
it returns.

The module is responsible for calling @code{_close} on the descriptor
after setting the handler function to zero in the extended close
handler.

@subheading Return Value

If successful, a new file descriptor is returned. On error, a negative number
is returned and @code{errno} is set to indicate the error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example

int socket()
@{
  int fd = __FSEXT_alloc_fd(socket_handler);
  init_socket(fd);
  return fd;
@}
@end example


@c -----------------------------------------------------------------------------
@node __FSEXT_call_open_handlers, __FSEXT_get_data, __FSEXT_alloc_fd, Alphabetical List
@unnumberedsec __FSEXT_call_open_handlers
@c From file ./fsext/fse_open.txh
@findex __FSEXT_call_open_handlers
@subheading Syntax

@example
#include <sys/fsext.h>

int __FSEXT_call_open_handlers(__FSEXT_Fnumber _function_number,
			       int *rv, va_list _args);
@end example

@subheading Description

This function is part of the @ref{File System Extensions}.  It is used
internally to libc.a to allow extensions to get an opportunity to
override the @code{_open} and @code{_creat} functions.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __FSEXT_get_data, __FSEXT_get_function, __FSEXT_call_open_handlers, Alphabetical List
@unnumberedsec __FSEXT_get_data
@c From file ./fsext/fsext.txh
@findex __FSEXT_get_data
@subheading Syntax

@example
#include <sys/fsext.h>

void *__FSEXT_get_data(int _fd);
@end example

@subheading Description

This function is part of the @ref{File System Extensions}.  It is used
to retrieve a descriptor-specific pointer that was previously stored
by @code{__FSEXT_set_data} (@pxref{__FSEXT_set_data}).  The pointer is not
otherwise used.

@xref{__FSEXT_set_data}, for an example of how this may be used.

@subheading Return Value

Returns the stored pointer, or NULL if there was an error (or no
pointer had been stored).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __FSEXT_get_function, __FSEXT_set_data, __FSEXT_get_data, Alphabetical List
@unnumberedsec __FSEXT_get_function
@c From file ./fsext/fsext.txh
@findex __FSEXT_get_function
@subheading Syntax

@example
#include <sys/fsext.h>

__FSEXT_Function *__FSEXT_get_function(int _fd);
@end example

This function is part of the @ref{File System Extensions}.  It is used
internal to libc.a to redirect I/O requests to the appropriate
extensions.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
_read(int fd, void *buf, int len)
@{
  __FSEXT_Function *func = __FSEXT_get_function(fd);
  if (func)
  @{
    int rv;
    if (__FSEXT_func_wrapper(func, __FSEXT_read, &rv, fd))
      return rv;
  @}
  /* rest of read() */
@}
@end example

@c -----------------------------------------------------------------------------
@node __FSEXT_set_data, __FSEXT_set_function, __FSEXT_get_function, Alphabetical List
@unnumberedsec __FSEXT_set_data
@c From file ./fsext/fsext.txh
@findex __FSEXT_set_data
@subheading Syntax

@example
#include <sys/fsext.h>

void * __FSEXT_set_data(int _fd, void *_data);
@end example

@subheading Description

This function is part of the @ref{File System Extensions}.  It is used
to store a descriptor-specific pointer that can later be retrieved by
@code{__FSEXT_get_data} (@pxref{__FSEXT_get_data}).  The pointer is not
otherwise used.

This is useful when writing an extension that may be handling several
open pseudo-files.  @code{__FSEXT_set_data} can be used when creating or
opening the file to store a pointer to data about the specific file.  Later,
when specific operation needs to be done (e.g. read, write, etc.) a
pointer to pseudo-file associated with the file descriptor can  be fetched
with @code{__FSEXT_get_data}.

@subheading Return Value

Returns the pointer you passed it, or NULL if there was an error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
typedef struct
@{
   void* Ptr;
   off_t Current_Ofs;
   size_t Size;
@} _mem_file_t;

int my_fsext(__FSEXT_Fnumber Op, int* RV, va_list Args)
@{
   const char* Path;
   void* Buffer;
   size_t Size;
   int fd;
   _mem_file_t* MPtr;

   switch (Op)
   @{
      case __FSEXT_creat:
       /* Create a new memory file */

       Path = va_list(Args, const char*);

       /* Check to see if we should create a new file */
       if (strnicmp("/tmp/", Path, 5) != 0) return 0;

       /* Allocate some memory to keep info on our fake file */
       MPtr = malloc(sizeof(_mem_file_t));
       if (!MPtr) return 0;

       memset(MPtr, 0, sizeof(_mem_file_t));

       /* Get a file descriptor we can use */
       fd = __FSEXT_alloc_fd(my_fsext);
       if (fd < 0)
       @{
          free(MPtr);
          return 0;
       @}

       /* Now store our note about this file descriptor so we can
        * look it up quickly later. */
       __FSEXT_set_data(fd, MPtr);

       /* Return the file descriptor
       *RV = fd;
       return 1;

      case __FSEXT_read:
       /* Read from our memory file. */
       fd = va_list(Args, int);
       Buffer = va_list(Args, void*);
       Size = va_list(Args, size_t);

       /* Look up the information about this file */
       MPtr = __FSEXT_get_data(fd);
       if (!MPtr)
       @{
           *RV = -1;
           return 1;
       @}

       if (MPtr->Current_Ofs >= MPtr->Size)
       @{
           *RV = 0;
           return 1;
       @}

       if (Size > (MPtr->Size - MPtr->Current_Ofs))
        Size = MPtr->Size - MPtr->Current_Ofs;

       memcpy(Buffer, (char*) MPtr->Ptr+MPtr->Current_Ofs, Size);
       MPtr->Current_Ofs += Size;

       *RV = Size;
       return 1;
       
       ...
    @}
@}
@end example

@c -----------------------------------------------------------------------------
@node __FSEXT_set_function, fstat, __FSEXT_set_data, Alphabetical List
@unnumberedsec __FSEXT_set_function
@c From file ./fsext/fsext.txh
@findex __FSEXT_set_function
@subheading Syntax

@example
#include <sys/fsext.h>

int __FSEXT_set_function(int _fd, __FSEXT_Function *_function);
@end example

@subheading Description

This function is part of the @ref{File System Extensions}.  It is used
to set the handler function for those extensions that use DOS files
for I/O.  One situation where you might need this is when you must catch
output to the terminal and play some tricks with it, like colorize it or
redirect it to another device.

@subheading Return Value

Zero in case of success, non-zero in case of failure (like if @var{_fd}
is negative).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example

#include <sys/fsext.h>
#include <conio.h>

/* A simple example of a write handler which converts DOS I/O to the
   screen into direct writes to video RAM.  */
static int
my_screen_write (__FSEXT_Fnumber func, int *retval, va_list rest_args)
@{
  char *buf, *mybuf;
  size_t buflen;
  int fd = va_arg (rest_args, int);

  if (func != __FSEXT_write || !isatty (fd))
    return 0;  /* and the usual DOS call will be issued */

  buf = va_arg (rest_args, char *);
  buflen = va_arg (rest_args, size_t);
  mybuf = alloca (buflen + 1);
  memcpy (mybuf, buf, buflen);
  mybuf[buflen] = '\0';
  cputs (mybuf);
  *retval = buflen;
  return 1;  /* meaning that we handled the call */
@}

/* Install our handler.  The `attribute constructor' causes this
   function to be called by the startup code.  */
static void __attribute__((constructor))
install_screen_write_handler (void)
@{
  __FSEXT_set_function (fileno (stdout), my_screen_write);
@}

@end example


@c -----------------------------------------------------------------------------
@node fstat, fstatvfs, __FSEXT_set_function, Alphabetical List
@unnumberedsec fstat
@c From file ./posix/sys/stat/fstat.txh
@findex fstat
@subheading Syntax

@example
#include <sys/stat.h>

int fstat(int file, struct stat *sbuf);
@end example

@subheading Description

This function obtains the status of the open file @var{file} and stores
it in @var{sbuf}.  @xref{stat}, for the description of members of
@code{struct stat}.

The @code{st_size} member is an signed 32-bit integer type, so it will
overflow on FAT32 volumes for files that are larger than 2GB.
Therefore, if your program needs to support large files, you should
treat the value of @code{st_size} as an unsigned value.

For some drives @code{st_blksize} has a default value, to improve
performance.  The floppy drives A: and B: default to a block size
of 512 bytes.  Network drives default to a block size of 4096 bytes.

Some members of @code{struct stat} are very expensive to compute.  If
your application is a heavy user of @code{fstat} and is too slow, you
can disable computation of the members your application doesn't need, as
described in @ref{_djstat_flags}.

@subheading Return Value

Zero on success, nonzero on failure (and @code{errno} set). 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
struct stat s;
fstat(fileno(stdin), &s);
if (S_ISREG(s.st_mode))
  puts("STDIN is a redirected disk file");
else if (S_ISCHR(s.st_mode))
  puts("STDIN is a character device");
@end example

@subheading Bugs

If a file was open in write-only mode, its execute and symlink mode 
bits might be incorrectly reported as if the file were non-executable
or non-symlink.  This is because executables and symlinks are only 
recognized by reading their first few bytes, which cannot be done for 
files open in write-only mode.

For @code{fstat} to return correct info, you should make sure that all
the data written to the file has been delivered to the operating system,
e.g. by calling both @code{fflush} and @code{fsync}.  Otherwise, the
buffering of the library I/O functions and the OS might cause stale info
to be returned.

@subheading Implementation Notes

Supplying a 100% Unix-compatible @code{fstat} function under DOS is an
implementation nightmare.  The following notes describe some of the
obscure points specific to @code{fstat}s behavior in DJGPP.

1. The @samp{drive} for character devices (like @code{con}, @code{/dev/null}
and others is returned as -1.  For drives networked by Novell Netware, it
is returned as -2.

2. The starting cluster number of a file serves as its inode number.
For files whose starting cluster number is inaccessible (empty files,
all files on Windows, files on networked drives, etc.) the
@code{st_inode} field will be @cite{invented} in a way which guarantees
that no two different files will get the same inode number (thus it is
unique).  This invented inode will also be different from any real
cluster number of any local file.  However, only for local, non-empty
files/directories the inode is guaranteed to be consistent between
@code{stat} and @code{fstat} function calls.  (Note that files on
different drives can have identical inode numbers, and thus comparing
files for identity should include comparison of the @code{st_dev}
member.)

3. On all versions of Windows except Windows 3.X, the inode number is
invented using the file name.  @code{fstat} can probably use the file name
that was used to open the file, when generating the inode.  This is done
such that the same inode will be generated irrespective of the actual path
used to open the file (e.g.: @file{foo.txt}, @file{./foo.txt},
@file{../somedir/foo.txt}).  If file names cannot be used, @code{fstat}
always returns different inode numbers for any two files open
on different handles, even if the same file is open twice
on two different handles.

4. The WRITE access mode bit is set only for the user (unless the file is
read-only, hidden or system).  EXECUTE bit is set for directories,  files
which can be executed from the DOS prompt (batch files, .com, .dll and .exe
executables) or run by @code{go32-v2.exe}.  For files which reside on
networked drives under Novell Netware, this can sometimes fail, in which
case only the read access bit is set.

5. The variable @code{_djstat_flags} (@pxref{_djstat_flags}) controls
what hard-to-get fields of @code{struct stat} are needed by the
application.
@c -----------------------------------------------------------------------------
@node fstatvfs, fsync, fstat, Alphabetical List
@unnumberedsec fstatvfs
@c From file ./posix/sys/statvfs/fstatvfs.txh
@findex fstatvfs
@subheading Syntax

@example
#include <sys/types.h>
#include <sys/statvfs.h>

int fstatvfs (int fd, struct statvfs *sbuf);
@end example

@subheading Description

This function returns information about the ``filesystem'' (FS)
containing the file referred to by the file descriptor @var{fd}
and stores it in @var{sbuf}, which has the structure below:

@example
struct statvfs @{
  unsigned long f_bsize;   /* FS block size */
  unsigned long f_frsize;  /* fundamental block size */
  fsblkcnt_t    f_blocks;  /* # of blocks on filesystem */
  fsblkcnt_t    f_bfree;   /* # of free blocks on FS */
  fsblkcnt_t    f_bavail;  /* # of free blocks on FS for
                            * unprivileged users */
  fsfilcnt_t    f_files;   /* # of file serial numbers */
  fsfilcnt_t    f_ffree;   /* # of free file serial numbers */
  fsfilcnt_t    f_favail;  /* # of free file serial numbers
                            * for unprivileged users */
  unsigned long f_fsid;    /* FS identifier */
  unsigned long f_flag;    /* FS flags: bitwise OR of ST_NOSUID,
                            * ST_RDONLY */
  unsigned long f_namemax; /* Maximum file name length on FS */
@};
@end example

Note that if INT 21h is hooked by a TSR, the total size is limited
to approximately 2GB (@pxref{statvfs}).

@subheading Return Value

Zero on success, nonzero on failure (and @code{errno} set).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable

@c -----------------------------------------------------------------------------
@node fsync, ftell, fstatvfs, Alphabetical List
@unnumberedsec fsync
@c From file ./compat/unistd/fsync.txh
@findex fsync
@subheading Syntax

@example
#include <unistd.h>

int fsync(int file);
@end example

@subheading Description

Forces all information about the file with the given descriptor to be
synchronized with the disk image.  Works by calling DOS function 0x68.
@emph{Warning}: External disk caches are not flushed by this function.

@code{fsync} does not support directories.

@subheading Return Value

Zero on success, nonzero on failure. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
fsync(fileno(stdout));
@end example

@c -----------------------------------------------------------------------------
@node ftell, ftello, fsync, Alphabetical List
@unnumberedsec ftell
@c From file ./ansi/stdio/ftell.txh
@findex ftell
@subheading Syntax

@example
#include <stdio.h>

long ftell(FILE *file);
@end example

@subheading Description

Returns the current file position for @code{file}.  This is suitable for
a future call to @code{fseek}. 

@subheading Return Value

The file position, or -1 on error. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
long p = ftell(stdout);
@end example

@c -----------------------------------------------------------------------------
@node ftello, ftime, ftell, Alphabetical List
@unnumberedsec ftello
@c From file ./compat/stdio/ftello.txh
@findex ftello
@subheading Syntax

@example
#include <stdio.h>

off_t ftello(FILE *file);
@end example

@subheading Description

@code{ftello} is a wrapper function of @code{ftell} (@pxref{ftell}).
So it is identical to @code{ftell}, except that the return value of
@code{ftello} is of type @code{off_t} instead of @code{long}.

Returns the current file position for @code{file}.  This is suitable for
a future call to @code{fseeko}. 

@subheading Return Value

The file position, or -1 on error. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
off_t p = ftello(stdout);
@end example

@c -----------------------------------------------------------------------------
@node ftime, ftruncate, ftello, Alphabetical List
@unnumberedsec ftime
@c From file ./dos/sys/timeb/ftime.txh
@findex ftime
@tindex timeb@r{ structure}
@subheading Syntax

@example
#include <sys/timeb.h>

int ftime(struct timeb *buf);
@end example

@subheading Description

This function stores the current time in the structure @var{buf}.  The
format of @code{struct timeb} is:

@example
struct timeb @{
  time_t         time;     /* seconds since 00:00:00 GMT 1/1/1970 */
  unsigned short millitm;  /* milliseconds */
  short          timezone; /* difference between GMT and local,
                            * minutes */
  short          dstflag;  /* set if daylight savings time in affect */
@};
@end example

@subheading Return Value

Zero on success, nonzero on error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
struct timeb t;
ftime(&t);
@end example

@c -----------------------------------------------------------------------------
@node ftruncate, ftw, ftime, Alphabetical List
@unnumberedsec ftruncate
@c From file ./compat/unistd/ftruncat.txh
@findex ftruncate
@subheading Syntax

@example
#include <unistd.h>

int ftruncate(int handle, off_t where);
@end example

@subheading Description

This function truncates the file open on @var{handle} at byte position
@var{where}.  The file pointer associated with @var{handle} is not
changed.

Note that this function knows nothing about buffering by stdio functions
like @code{fwrite} and @code{fprintf}, so if @var{handle} comes from a
@code{FILE} object, you need to call @code{fflush} before calling this
function.

@code{ftruncate} does not support directories.

@subheading Return Value

Zero for success, nonzero for failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
int x = open("data", O_WRONLY);
ftruncate(x, 1000);
close(x);
@end example

@c -----------------------------------------------------------------------------
@node ftw, _fwalk, ftruncate, Alphabetical List
@unnumberedsec ftw
@c From file ./dos/dir/ftw.txh
@findex ftw
@subheading Syntax

@example
#include <ftw.h>

int ftw(const char *dir, 
        int (*func)(const char *path, struct stat *stbuf, int flag),
        int depth);
@end example

@subheading Description

This function recursively descends the directory hierarchy which starts
with @var{dir}.  For each file in the hierarchy, @code{ftw} calls the
user-defined function @var{func} which is passed a pointer to a
@code{NULL}-terminated character array in @var{path} holding the full
pathname of the file, a pointer to a @code{stat} structure (@pxref{stat})
@var{stbuf} with a filesystem information about that file, and an integer
@var{flag}.  Possible values of @var{flag} are:

@table @code

@item FTW_F

This is a regular file.

@item FTW_D

This is a directory.

@item FTW_VL

This is a volume label.

@item FTW_DNR

This is a directory which cannot be read with @code{readdir()}.  (This
will never happen in DJGPP.)

@item FTW_NS

This file exists, but @code{stat} fails for it.

@end table

If @var{flag} is @code{FTW_DNR}, the descendants of that directory won't
be processed.  If @var{flag} is @code{FTW_NS}, then @var{stbuf} will be
garbled.

This function always visits a directory before any of its siblings.  The
argument @var{dir} must be a directory, or @code{ftw} will fail and set
@code{errno} to @code{ENOTDIR}.  The function @var{func} is called with
@var{dir} as its argument before the recursive descent begins.

The @var{depth} argument has no meaning in the DJGPP implementation and is
always ignored.

The tree traversal continues until one of the following events:

(1)  The tree is exhausted (i.e., all descendants of @var{dir} are
processed).  In this case, @code{ftw} returns 0, meaning a success.

(2)  An invocation of @var{func} returns a non-zero value.  In this case,
@code{ftw} stops the tree traversal and returns whatever @var{func}
returned.

(3)  An error is detected within @code{ftw}.  In that case, @code{ftw}
returns -1 and sets @code{errno} (@pxref{errno}) to a suitable value.

@subheading Return Value

Zero in case the entire tree was successfully traversed, -1 if @code{ftw}
detected some error during its operation, or any other non-zero value
which was returned by the user-defined function @var{func}.

@subheading Implementation Notes

This function uses @code{malloc} (@pxref{malloc}) for dynamic memory
allocation during its operation.  If @var{func} disrupts the normal flow
of code execution by e.g. calling @code{longjump} or if an interrupt
handler which never returns is executed, this memory will remain
permanently allocated.

This function calls @code{opendir()} and @code{readdir()} functions to
read the directory entries.  Therefore, you can control what files will
your @var{func} get by setting the appropriate bits in the external
variable @var{__opendir_flags}.  @xref{opendir}, for description of these
bits.

This function also calls @code{stat} for every directory entry it passes
to @var{func}.  If your application only needs some part of the
information returned in the @code{stat} structure, you can make your
application significantly faster by setting bits in the external variable
@var{_djstat_flags} (@pxref{_djstat_flags} for details).  The most
expensive @code{stat} features are @code{_STAT_EXEC_MAGIC} and
@code{_STAT_DIRSIZE}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
#include <stdlib.h>

int
file_walker(const char *path, struct stat *sb, int flag)
@{
  char *base;

  printf("%s:\t%u\t", path, sb->st_size);
  if (S_ISLABEL(sb->st_mode))
    printf("V");
  if (S_ISDIR(sb->st_mode))
    printf("D");
  if (S_ISCHR(sb->st_mode))
    printf("C");
  if (sb->st_mode & S_IRUSR)
    printf("r");
  if (sb->st_mode & S_IWUSR)
    printf("w");
  if (sb->st_mode & S_IXUSR)
    printf("x");

  if (flag == FTW_NS)
    printf("  !!no_stat!!");
  printf("\n");

  base = strrchr(path, '/');
  if (base == 0)
    base = strrchr(path, '\\');
  if (base == 0)
    base = strrchr(path, ':');
  if (strcmp(base == 0 ? path : base + 1, "xxxxx") == 0)
    return 42;
  return 0;
@}

int
main(int argc, char *argv[])
@{
  if (argc > 1)
    @{
      char msg[80];

      sprintf(msg, "file_tree_walk: %d",
                   ftw(argv[1], file_walker, 0));
      if (errno)
        perror(msg);
      else
        puts(msg);
    @}
  else
    printf("Usage: %s dir\n", argv[0]);

  return 0;
@}
@end example
@c -----------------------------------------------------------------------------
@node _fwalk, fwrite, ftw, Alphabetical List
@unnumberedsec _fwalk
@c From file ./ansi/stdio/fwalk.txh
@findex _fwalk
@subheading Syntax

@example
#include <libc/file.h>

void _fwalk(void (*function)(FILE *file));
@end example

@subheading Description

For each open file in the system, the given @var{function} is called,
passing the file pointer as its only argument.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
void pfile(FILE *x)
@{ printf("FILE at %p\n", x); @}

_fwalk(pfile);
@end example
@c -----------------------------------------------------------------------------
@node fwrite, gcvt, _fwalk, Alphabetical List
@unnumberedsec fwrite
@c From file ./ansi/stdio/fwrite.txh
@findex fwrite
@subheading Syntax

@example
#include <stdio.h>

size_t fwrite(void *buffer, size_t size, size_t number, FILE *file);
@end example

@subheading Description

This function writes @var{size}*@var{number} characters from @var{buffer}
to @var{file}.

@subheading Return Value

The number of items of size @var{size} written, or less if there was
an error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
int foo[10];
fwrite(foo, sizeof(int), 10, stdin);
@end example


@c -----------------------------------------------------------------------------
@node gcvt, _get_dev_info, fwrite, Alphabetical List
@unnumberedsec gcvt
@c From file ./compat/stdlib/itoa.txh
@findex gcvt
@subheading Syntax

@example
#include <stdlib.h>

char * gcvt (double value, int ndigits, char *buf)
@end example

@subheading Description

This function converts its argument @var{value} into a null-terminated
string of @var{ndigits} significant digits in @var{buf}.  @var{buf}
should have enough space to hold at least @code{@var{ndigits} + 7}
characters.  The result roughly corresponds to what is obtained by the
following snippet:

@example
 (void) sprintf(buf, "%.*g", ndigits, value);
@end example

@noindent
except that trailing zeros and trailing decimal point are suppressed.

The least-significant digit in @var{buf} is rounded.

@code{ecvtbuf} produces the string ``NaN'' if @var{value} is a NaN, and
``Inf'' if @var{value} is an infinity.

@subheading Return Value

A pointer to @var{buf}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  #include <stdlib.h>
  #include <stdio.h>
  #include <math.h>

  char vbuf[20];

  /* This will print " 3.14159".  */
  printf ("%s", gcvt (M_PI, 5, buf));
@end example

@c -----------------------------------------------------------------------------
@node _get_dev_info, _get_dos_version, gcvt, Alphabetical List
@unnumberedsec _get_dev_info
@c From file ./dos/dos/getdinfo.txh
@findex _get_dev_info
@cindex cooked mode
@cindex raw mode
@subheading Syntax

@example
#include <io.h>

short _get_dev_info(int handle);
@end example

@subheading Description

Given a file handle in @var{handle}, this function returns the info word
from DOS IOCTL function 0 (Int 21h/AX=4400h).  @var{handle} must refer
to an open file or device, otherwise the call will fail (and set
@code{errno} to @code{EBADF}).

In case of success, the returned value is the coded information from the
system about the character device or the file which is referenced by the
file handle @var{handle}.  The header @code{<libc/getdinfo.h>} defines
constants for the individual bits in the return value.  The following table
shows the meaning of the individual bits in the return value:

For a character device:

@multitable {Bit(s)} {@code{_DEV_STDOUT}} {Device can process IOCTL functions 02h and 03h}
@item Bit(s)
@tab Constant
@tab Description

@item 14
@tab @code{_DEV_IOCTRL}
@tab Device can process IOCTL functions 02h and 03h

@item 13
@tab
@tab Device supports output-until-busy

@item 11
@tab
@tab Device supports OPEN/CLOSE calls

@item 8
@tab
@tab Unknown; set by MS-DOS 6.2x @file{KEYB@var{xx}.COM}

@item 7
@tab @code{_DEV_CDEV}
@tab Always set for character devices

@item 6
@tab
@tab End of file on input

@item 5
@tab @code{_DEV_RAW}
@tab If set, device is in @strong{raw} (binary) mode

@item 5
@tab @code{_DEV_RAW}
@tab If clear, device is in @strong{cooked} (text) mode

@item 4
@tab
@tab Device uses Int 29h

@item 3
@tab @code{_DEV_CLOCK}
@tab Clock device

@item 2
@tab @code{_DEV_NUL}
@tab NUL device

@item 1
@tab @code{_DEV_STDOUT}
@tab Standard output device

@item 0
@tab @code{_DEV_STDIN}
@tab Standard input device
@end multitable

For a block device (a disk file):

@multitable {Bit(s)} {@code{_DEV_STDOUT}} {Generate Int 24h if full disk or read past EOF}
@item Bit(s)
@tab Constant
@tab Description

@item 15
@tab @code{_DEV_REMOTE}
@tab Device is remote (networked drive)

@item 14
@tab
@tab Don't set file time stamp on close

@item 11
@tab
@tab If set, non-removable media

@item 11
@tab
@tab If clear, media is removable (e.g.@: floppy disk)

@item 8
@tab
@tab Generate Int 24h if full disk or read past EOF

@item 7
@tab @code{_DEV_CDEV}
@tab Always clear for disk files

@item 6
@tab
@tab File has not been written to

@item 5-0
@tab
@tab Drive number (0 = @file{A:})
@end multitable

Note that the functionality indicated by bit 8 for the block devices is
only supported by DOS version 4.

@dfn{Cooked} mode means that on input @kbd{C-@key{C}}, @kbd{C-@key{P}},
@kbd{C-@key{S}} and @kbd{C-@key{Z}} are processed, on output @samp{TAB}s
are expanded into spaces and @samp{CR} character is added before each
@samp{LF}, and input is terminated when the @key{RET} key is pressed.
In contrast, in @dfn{raw} mode, all the special characters are passed
verbatim, and the read operation waits until the specified number of
characters has been read.

@subheading Return Value

The device information word described above.  In case of error, -1 is
returned and @code{errno} is set to @code{EBADF}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
 int fd = open ("CLOCK$", O_RDONLY | O_BINARY);
 int clock_info = _get_dev_info (fd);
@end example
@c -----------------------------------------------------------------------------
@node _get_dos_version, __get_extended_key_string, _get_dev_info, Alphabetical List
@unnumberedsec _get_dos_version
@c From file ./dos/dos/getdos_v.txh
@findex _get_dos_version
@subheading Syntax

@example
#include <dos.h>

extern unsigned short   _osmajor, _osminor;
extern unsigned short   _os_trueversion;
extern const    char  * _os_flavor;

unsigned short _get_dos_version(int true_version);
@end example

@subheading Description

This function gets the host OS version and flavor.  If the argument
@var{true_version} is non-zero, it will return a @cite{true} version
number, which is unaffected by possible tinkering with SETVER TSR program.
(This is only available in DOS 5.0 or later.)

The external variables @code{_osmajor} and @code{_osminor} will always be
set to the major and minor parts of the @cite{advertised} version number.
The external variable @code{_os_trueversion} will always be set to the
true version number.  @code{_osmajor}, @code{_osminor}
and @code{_os_trueversion} may possibly be changed by @code{SETVER},
even if @var{true_version} is non-zero.

You typically need the true version when you need an intimate knowledge
of the host OS internals, like when using undocumented features.  Note
that some DOS clones (notably, DR-DOS) do not support DOS function
required to report the true DOS version; for these, the version
reported might be affected by @code{SETVER} even if @var{true_version}
is non-zero.

The external variable @code{_os_flavor} will point to a string which
describes the OEM name of the host OS variety.

@subheading Return Value

@code{_get_dos_version()} returns the version number (true version number,
if @var{true_version} is non-zero) as a 16-bit number: the major part of
the version in the upper 8 bits, the minor part in the lower 8 bits.  For
instance, DOS version 6.20 will be returned as 0x0614.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  unsigned short true_dos_version = _get_dos_version(1);

  if (true_dos_version < 0x0614)   /* require DOS 6.20 or later */
    puts("This program needs DOS 6.20 or later to run");
  else
    printf("You are running %s variety of DOS\n", _os_flavor);
@end example

@c -----------------------------------------------------------------------------
@node __get_extended_key_string, _get_fat_size, _get_dos_version, Alphabetical List
@unnumberedsec __get_extended_key_string
@c From file ./pc_hw/kb/getxkstr.txh
@findex __get_extended_key_string
@subheading Syntax

@example
#include <pc.h>

const unsigned char * __get_extended_key_string(int xkey_code);
@end example

@subheading Description

Returns an @sc{ecma-48} compliant representation of an extended key's
scan code in @var{xkey_code}.

@xref{getkey}.
@xref{getxkey}.

@subheading Return Value

A string based on the extended key's scan code @var{xkey_code}:

@multitable {@kbd{Page Down}} {@code{ESC[24~}} {with Shift} {with Ctrl} {@code{ESC[80~}}
@item Key @tab Normal @tab with Shift  @tab with Ctrl   @tab with Alt

@item @kbd{Up Arrow}
@tab @code{ESC[A}   @tab @tab @code{ESC[37~} @tab @code{ESC[59~}

@item @kbd{Down Arrow}
@tab @code{ESC[B}   @tab @tab @code{ESC[38~} @tab @code{ESC[60~}

@item @kbd{Left Arrow}
@tab @code{ESC[C}   @tab @tab @code{ESC[39~} @tab @code{ESC[61~}

@item @kbd{Right Arrow}
@tab @code{ESC[D}   @tab @tab @code{ESC[40~} @tab @code{ESC[62~}

@item @kbd{Home}
@tab @code{ESC[1~}  @tab @tab @code{ESC[41~} @tab @code{ESC[63~}

@item @kbd{Insert}
@tab @code{ESC[2~}  @tab @tab @code{ESC[42~} @tab @code{ESC[64~}

@item @kbd{Delete}
@tab @code{ESC[3~}  @tab @tab @code{ESC[43~} @tab @code{ESC[65~}

@item @kbd{End}
@tab @code{ESC[4~}  @tab @tab @code{ESC[44~} @tab @code{ESC[66~}

@item @kbd{Page Up}
@tab @code{ESC[5~}  @tab @tab @code{ESC[45~} @tab @code{ESC[67~}

@item @kbd{Page Down}
@tab @code{ESC[6~}  @tab @tab @code{ESC[46~} @tab @code{ESC[68~}

@item @kbd{F1}
@tab @code{ESC[[A}  @tab @code{ESC[25~} @tab @code{ESC[47~} @tab @code{ESC[69~}

@item @kbd{F2}
@tab @code{ESC[[B}  @tab @code{ESC[26~} @tab @code{ESC[48~} @tab @code{ESC[70~}

@item @kbd{F3}
@tab @code{ESC[[C}  @tab @code{ESC[27~} @tab @code{ESC[49~} @tab @code{ESC[71~}

@item @kbd{F4}
@tab @code{ESC[[D}  @tab @code{ESC[28~} @tab @code{ESC[50~} @tab @code{ESC[72~}

@item @kbd{F5}
@tab @code{ESC[[E}  @tab @code{ESC[29~} @tab @code{ESC[51~} @tab @code{ESC[73~}

@item @kbd{F6}
@tab @code{ESC[17~} @tab @code{ESC[30~} @tab @code{ESC[52~} @tab @code{ESC[74~}

@item @kbd{F7}
@tab @code{ESC[18~} @tab @code{ESC[31~} @tab @code{ESC[53~} @tab @code{ESC[75~}

@item @kbd{F8}
@tab @code{ESC[19~} @tab @code{ESC[32~} @tab @code{ESC[54~} @tab @code{ESC[76~}

@item @kbd{F9}
@tab @code{ESC[20~} @tab @code{ESC[33~} @tab @code{ESC[55~} @tab @code{ESC[77~}

@item @kbd{F10}
@tab @code{ESC[21~} @tab @code{ESC[34~} @tab @code{ESC[56~} @tab @code{ESC[78~}

@item @kbd{F11}
@tab @code{ESC[23~} @tab @code{ESC[35~} @tab @code{ESC[57~} @tab @code{ESC[79~}

@item @kbd{F12}
@tab @code{ESC[24~} @tab @code{ESC[36~} @tab @code{ESC[58~} @tab @code{ESC[80~}

@end multitable

@multitable {@kbd{Alt-A}} {@code{ESC[83~}} {@code{Alt-Z}} {@code{ESC[113~}}
@item Alt Key @tab  @tab Alt Key @tab
@item @kbd{Alt-A} @tab @code{ESC[81~}
 @tab @kbd{Alt-N} @tab @code{ESC[94~}
@item @kbd{Alt-B} @tab @code{ESC[82~}
 @tab @kbd{Alt-O} @tab @code{ESC[95~}
@item @kbd{Alt-C} @tab @code{ESC[83~}
 @tab @kbd{Alt-P} @tab @code{ESC[96~}
@item @kbd{Alt-D} @tab @code{ESC[84~}
 @tab @kbd{Alt-Q} @tab @code{ESC[97~}
@item @kbd{Alt-E} @tab @code{ESC[85~}
 @tab @kbd{Alt-R} @tab @code{ESC[98~}
@item @kbd{Alt-F} @tab @code{ESC[86~}
 @tab @kbd{Alt-S} @tab @code{ESC[99~}
@item @kbd{Alt-G} @tab @code{ESC[87~}
 @tab @kbd{Alt-T} @tab @code{ESC[100~}
@item @kbd{Alt-H} @tab @code{ESC[88~}
 @tab @kbd{Alt-U} @tab @code{ESC[101~}
@item @kbd{Alt-I} @tab @code{ESC[89~}
 @tab @kbd{Alt-V} @tab @code{ESC[102~}
@item @kbd{Alt-J} @tab @code{ESC[90~}
 @tab @kbd{Alt-W} @tab @code{ESC[103~}
@item @kbd{Alt-K} @tab @code{ESC[91~}
 @tab @kbd{Alt-X} @tab @code{ESC[104~}
@item @kbd{Alt-L} @tab @code{ESC[92~}
 @tab @kbd{Alt-Y} @tab @code{ESC[105~}
@item @kbd{Alt-M} @tab @code{ESC[93~}
 @tab @kbd{Alt-Z} @tab @code{ESC[106~}
@end multitable

@code{NULL} is returned if @var{xkey_code} has no translation.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
#include <pc.h>
#include <stdio.h>

int key;

int main()
@{
  key = getxkey();
  if (key < 0x100)
  @{
    putc(key, stdout);
    putc('\r', stdout);
  @}
  else
  @{
    const unsigned char *str = __get_extended_key_string(key);
    if (str)
      puts(str);
    else
      puts("<unknown>");
  @}
  fflush(stdout);
@}

@end example

@example
#include <pc.h>
#include <stdio.h>
#include <dpmi.h>

int main()
@{
  __dpmi_regs r;
  const unsigned char *str;
  int is_extended_key;

  /* Wait for keypress. */
  r.h.ah = 0x11;
  __dpmi_int(0x16, &r);
  /* Print the encoding for function keys (F1, F2, etc.)
     and other extended keys (Home, End, etc.). */
  is_extended_key = (r.h.al == 0x00 || r.h.al == 0xe0);
  if (is_extended_key)
  @{
    str = __get_extended_key_string((int)r.h.ah)
    printf("Key encoding: %s", str);
  @}
@}

@end example

@c -----------------------------------------------------------------------------
@node _get_fat_size, __get_fd_flags, __get_extended_key_string, Alphabetical List
@unnumberedsec _get_fat_size
@c From file ./dos/dos/getfatsz.txh
@findex _get_fat_size
@subheading Syntax

@example
#include <dos.h>

int _get_fat_size( const int drive );
@end example

@subheading Description

This function tries to determine the number of bits used to enumerate
the clusters by the FAT on drive number @var{drive}. 1 == A:, 2 == B:,
etc., 0 == default drive.  

This function will not succeed on DOS version < 4, setting
@code{errno} to @code{ENOSYS}.  It is also known to have trouble
detecting the file system type of disks formatted with a later version
of DOS than the version it is run on.  E. g. floppies with LFN
entries can cause this function to fail or detect the fat size as 16
if used in plain DOS.  

If you are looking for a function that is able to detect other file
systems, perhaps the function @code{_get_fs_type}
(@pxref{_get_fs_type}) can be of use.  

@subheading Return Value

The number of bits used by the FAT (12, 16 or 32).  0 if the drive was
formatted with FAT but of unknown size (NT reports that on FAT16).  
-1 on error. 


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

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

int main(void)
@{
  int size;

  size = _get_fat_size( 'C' - 'A' + 1 );
  if( 0 <= size )
  @{
    printf("The size of FAT on C: is %d bits.\n", size);
  @}

  exit(0);
@}

@end example
@c -----------------------------------------------------------------------------
@node __get_fd_flags, __get_fd_name, _get_fat_size, Alphabetical List
@unnumberedsec __get_fd_flags
@c From file ./dos/io/fd_props.txh
@findex __get_fd_flags
@subheading Syntax

@example
#include <libc/fd_props.h>

unsigned long __get_fd_flags(int fd);
@end example

@subheading Description

This internal functions gets the flags associated with file descriptor
@var{fd}, if any.  The flags are some properties that may be associated
with a file descriptor (@pxref{__set_fd_properties}).

This function will return zero, if no flags are associated
with @var{fd}.  The caller should first check that there are flags
associated with @var{fd} using @code{__has_fd_properties}
(@pxref{__has_fd_properties}), before calling @code{__get_fd_flags}.
This will allow the cases of no flags and the flags being zero
to be distinguished.

@subheading Return Value

The flags, if any; otherwise zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __get_fd_name, _get_fs_type, __get_fd_flags, Alphabetical List
@unnumberedsec __get_fd_name
@c From file ./dos/io/fd_props.txh
@findex __get_fd_name
@subheading Syntax

@example
#include <libc/fd_props.h>

const char *__get_fd_name(int fd);
@end example

@subheading Description

This internal function gets the file name associated with
the file descriptor @var{fd}, if any.  The file name is one property
that may be associated with a file descriptor
(@pxref{__set_fd_properties}).

@subheading Return Value

A pointer to the file name, if any; otherwise @code{NULL}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable

@c -----------------------------------------------------------------------------
@node _get_fs_type, _get_volume_info, __get_fd_name, Alphabetical List
@unnumberedsec _get_fs_type
@c From file ./dos/dos/getfstyp.txh
@findex _get_fs_type
@subheading Syntax

@example
#include <dos.h>

int _get_fs_type( const int drive,
                  char *const result_str );
@end example

@subheading Description

This function tries to extract the file system type of the drive
number @var{drive}, 1 == A:, 2 == B:, etc., 0 == default drive.  It
does this by calling INT21, AX=0x6900, Get Disk Serial Number (sic!),
which returns, among other things, an eight character field which is
set while formatting the drive. Now, this field can be set to whatever
the formatting program wishes, but so far every FAT formatted drive
has returned a string starting with "FAT".  

If successful the result is put in @var{result_str} which must be at 
least 9 characters long.  If unsuccessful @code{errno} is set.  

This function will not succeed on DOS version < 4, setting
@code{errno} to @code{ENOSYS}.  It is also known to have trouble
detecting the file system type of disks formatted with a later version
of DOS than the version it is run on.  E. g. floppies with LFN
entries can cause this function to fail or detect the floppy as
FAT16 if used in plain DOS.  

If you are interested in which kind of FAT file system that is in use
try the function @code{_get_fat_size} (@pxref{_get_fat_size}) which
will reliably detect the right kind of FAT file system.  

@subheading Return Value

0 if the file system type was extracted successfully; otherwise -1.  

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

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

int main(void)
@{
  char buffer[9];

  if( ! _get_fs_type( 3, buffer ) )
  @{
    printf("The file system on C: is '%s'.\n", buffer);
  @}

  exit(0);
@}

@end example
@c -----------------------------------------------------------------------------
@node _get_volume_info, getc, _get_fs_type, Alphabetical List
@unnumberedsec _get_volume_info
@c From file ./dos/lfn/_use_lfn.txh
@findex _get_volume_info
@subheading Syntax
 
@example
#include <fcntl.h>
 
unsigned _get_volume_info (const char *path, 
                           int *max_file_len, int *max_path_len, 
                           char *fsystype);
@end example
 
@subheading Description

This function returns filesystem information about the volume where
@var{path} resides.  Only the root directory name part is actually used;
if @var{path} does not specify the drive explicitly, or is a @code{NULL}
pointer, the current drive is used.  Upon return, the variable pointed
to by @var{max_file_len} contains the maximum length of a filename
(including the terminating zero), the variable pointed to by
@var{max_path_len} contains the maximum length of a pathname (including
the terminating zero), and a string that identifies the filesystem type
(e.g., ``FAT'', ``NTFS'' etc.) is placed into the buffer pointed to by
@var{fsystype}, which should be long enough (32 bytes are usually
enough).  If any of these pointers is a @code{NULL} pointer, it will be
ignored.  The function returns various flags that describe features
supported by the given filesystem as a bit-mapped number.  The following
bits are currently defined:

@table @code
@item _FILESYS_CASE_SENSITIVE
Specifies that file searches are case-sensitive.

@item _FILESYS_CASE_PRESERVED
Filename letter-case is preserved in directory entries.

@item _FILESYS_UNICODE
Filesystem uses Unicode characters in file and directory names.

@item _FILESYS_LFN_SUPPORTED
Filesystem supports the @dfn{Long File Name} (LFN) API.

@item _FILESYS_VOL_COMPRESSED
This volume is compressed.

@item _FILESYS_UNKNOWN
The underlying system call failed.  This usually means that the drive
letter is invalid, like when a floppy drive is empty or a drive with
that letter doesn't exist.
@end table


@subheading Return value

A combination of the above bits if the LFN API is supported, or 0 (and
@code{errno} set to @code{ENOSYS}) if the LFN API is not supported by
the OS.  If the LFN API is supported, but the drive letter is invalid,
the function returns @code{_FILESYS_UNKNOWN} and sets @code{errno} to
either @code{ENODEV} or @code{ENXIO}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable



@c -----------------------------------------------------------------------------
@node getc, getcbrk, _get_volume_info, Alphabetical List
@unnumberedsec getc
@c From file ./ansi/stdio/getc.txh
@findex getc
@subheading Syntax

@example
#include <stdio.h>

int getc(FILE *file);
@end example

@subheading Description

Get one character from @var{file}.

@subheading Return Value

The character ([0..255]) or @code{EOF} if eof or error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
int c;
while ((c=getc(stdin)) != EOF)
  putc(c, stdout);
@end example

@c -----------------------------------------------------------------------------
@node getcbrk, getch, getc, Alphabetical List
@unnumberedsec getcbrk
@c From file ./dos/dos/getcbrk.txh
@findex getcbrk
@subheading Syntax

@example
#include <dos.h>

int getcbrk(void);
@end example

@subheading Description

Get the setting of the Ctrl-C checking flag in MS-DOS.

@xref{setcbrk}.

@subheading Return Value

0 if not checking, 1 if checking.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node getch, getchar, getcbrk, Alphabetical List
@unnumberedsec getch
@c From file ./pc_hw/co80/conio.txh
@findex getch
@subheading Syntax

@example
#include <conio.h>

int     getch(void);
@end example

@subheading Description

A single character from the predefined standard input handle is read and
returned.  The input is not buffered.  If there is a character pending
from @code{ungetch} (@pxref{ungetch}), it is returned instead.  The
character is not echoed to the screen.  This function doesn't check for
special characters like @kbd{Ctrl-@key{C}}.

If the standard input handle is connected to the console, any pending
output in the @code{stdout} and @code{stderr} streams is flushed before
reading the input, if these streams are connected to the console.

@subheading Return Value

The character.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node getchar, getche, getch, Alphabetical List
@unnumberedsec getchar
@c From file ./ansi/stdio/getchar.txh
@findex getchar
@subheading Syntax

@example
#include <stdio.h>

int getchar(void);
@end example

@subheading Description

The same as @code{fgetc(stdin)} (@pxref{fgetc}).

@subheading Return Value

The character, or @code{EOF}.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node getche, getcwd, getchar, Alphabetical List
@unnumberedsec getche
@c From file ./pc_hw/co80/conio.txh
@findex getche
@subheading Syntax

@example
#include <conio.h>

int getche(void);
@end example

@subheading Description

A single character from the predefined standard input handle is read and
returned.  The input is not buffered.  If there is a character pending
from @code{ungetch} (@pxref{ungetch}), it is returned instead.  The
character is echoed to the screen.  This function doesn't check for
special characters like @kbd{Ctrl-@key{C}}.

If the standard input handle is connected to the console, any pending
output in the @code{stdout} and @code{stderr} streams is flushed before
reading the input, if these streams are connected to the console.

@subheading Return Value

The character.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node getcwd, getdate, getche, Alphabetical List
@unnumberedsec getcwd
@c From file ./posix/unistd/getcwd.txh
@findex getcwd
@subheading Syntax

@example
#include <unistd.h>

char *getcwd(char *buffer, int max);
@end example

@subheading Description

Get the current directory.  The return value includes the drive
specifier.

If @var{buffer} is @code{NULL}, @code{getcwd} allocates
a buffer of size @var{max} with @code{malloc}.  This is an extension
of the POSIX standard, which is compatible with the behaviour of glibc
(the C library used on Linux).

This call fails if more than @var{max} characters are required
to specify the current directory.

@subheading Return Value

The buffer, either @var{buffer} or a newly-allocated buffer, or
@code{NULL} on error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
The behaviour when @var{buffer} is @code{NULL} is unspecified for POSIX.

@end enumerate

@subheading Example

@example
char *buf = (char *)malloc(PATH_MAX);
if (buf && getcwd(buf, PATH_MAX))
@{
  printf("cwd is %s\n", buf);
  free(buf);
@}
@end example

@c -----------------------------------------------------------------------------
@node getdate, getdfree, getcwd, Alphabetical List
@unnumberedsec getdate
@c From file ./dos/dos/getdate.txh
@findex getdate
@tindex date@r{ structure}
@subheading Syntax

@example
#include <dos.h>

void getdate(struct date *);
@end example

@subheading Description

This function gets the current date.  The return structure is as follows:

@example
struct date @{
  short da_year;
  char  da_day;
  char  da_mon;
@};
@end example

@xref{setdate}. @xref{gettime}.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
struct date d;
getdate(&d);
@end example

@c -----------------------------------------------------------------------------
@node getdfree, getdisk, getdate, Alphabetical List
@unnumberedsec getdfree
@c From file ./dos/dos/getdfree.txh
@findex getdfree
@tindex dfree@r{ structure}
@subheading Syntax

@example
#include <dos.h>

void getdfree(unsigned char drive, struct dfree *ptr);
@end example

@subheading Description

This function gets information about the size and fullness of the given
drive (0=default, 1=A:, etc).  The return structure is as follows:

@example
struct dfree @{
  unsigned df_avail; /* number of available clusters */
  unsigned df_total; /* total number of clusters */
  unsigned df_bsec;  /* bytes per sector */
  unsigned df_sclus; /* sectors per cluster */
@};
@end example

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
struct dfree d;
getdfree(3, &d); /* drive C: */
@end example

@c -----------------------------------------------------------------------------
@node getdisk, getdtablesize, getdfree, Alphabetical List
@unnumberedsec getdisk
@c From file ./dos/dir/getdisk.txh
@findex getdisk
@subheading Syntax

@example
#include <dir.h>

int getdisk(void);
@end example

@subheading Description

Gets the current disk (0=A).

@xref{setdisk}.

@subheading Return Value

The current disk number.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
printf("This drive is %c:\n", getdisk() + 'A');
@end example
@c -----------------------------------------------------------------------------
@node getdtablesize, getegid, getdisk, Alphabetical List
@unnumberedsec getdtablesize
@c From file ./compat/unistd/getstubs.txh
@findex getdtablesize
@subheading Syntax

@example
#include <unistd.h>

int getdtablesize(void);
@end example

@subheading Description

Get the maximum number of open file descriptors the system supports. 

@subheading Return Value

255

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node getegid, getenv, getdtablesize, Alphabetical List
@unnumberedsec getegid
@c From file ./posix/unistd/getegid.txh
@findex getegid
@subheading Syntax

@example
#include <unistd.h>

int getegid(void);
@end example

@subheading Description

Get the effective group id.

@subheading Return Value

42


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node getenv, geteuid, getegid, Alphabetical List
@unnumberedsec getenv
@c From file ./ansi/stdlib/getenv.txh
@findex getenv
@subheading Syntax

@example
#include <stdlib.h>

char *getenv(const char *name);
@end example

@subheading Description

Get the setting of the environment variable @var{name}.  Do not alter or
free the returned value. 

@subheading Return Value

The value, or @code{NULL} if that variable does not exist.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
char *term = getenv("TERM");
@end example

@c -----------------------------------------------------------------------------
@node geteuid, getftime, getenv, Alphabetical List
@unnumberedsec geteuid
@c From file ./posix/unistd/geteuid.txh
@findex geteuid
@subheading Syntax

@example
#include <unistd.h>

int geteuid(void);
@end example

@subheading Description

Gets the effective UID.

@subheading Return Value

42


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node getftime, getgid, geteuid, Alphabetical List
@unnumberedsec getftime
@c From file ./dos/dos/getftime.txh
@findex getftime
@tindex ftime@r{ structure}
@subheading Syntax

@example
#include <dos.h>

int getftime(int handle, struct ftime *ptr);
@end example

@subheading Description

Get the timestamp for the given file handle.  The return structure is as
follows:

@example
struct ftime @{
  unsigned ft_tsec:5;	/* 0-29, double to get real seconds */
  unsigned ft_min:6;	/* 0-59 */
  unsigned ft_hour:5;	/* 0-23 */
  unsigned ft_day:5;	/* 1-31 */
  unsigned ft_month:4;	/* 1-12 */
  unsigned ft_year:7;	/* since 1980 */
@}
@end example

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
struct ftime t;
getftime(fd, &t);
@end example

@c -----------------------------------------------------------------------------
@node getgid, getgrent, getftime, Alphabetical List
@unnumberedsec getgid
@c From file ./posix/unistd/getgid.txh
@findex getgid
@subheading Syntax

@example
#include <unistd.h>

int getgid(void);
@end example

@subheading Description

Get the current group id.

@subheading Return Value

42


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node getgrent, getgrgid, getgid, Alphabetical List
@unnumberedsec getgrent
@c From file ./posix/grp/getgrent.txh
@findex getgrent
@tindex group@r{ structure}
@vindex GROUP@r{ environment variable, and group entries}
@subheading Syntax

@example
#include <grp.h>

struct group *getgrent(void);
@end example

@subheading Description

This function returns the next available group entry.  Note that for
MS-DOS, this is simulated.  If the environment variable @code{GROUP} is set,
that is the name of the only group returned, else the only group is
"dos".  Thus, under DOS, @code{getgrent} will always fail on the
second and subsequent calls.

The return type of this and related function is as follows:

@example
struct group @{
  gid_t    gr_gid;    /* result of getgid() */
  char  ** gr_mem;    /* gr_mem[0] points to
                          getenv("USER"/"LOGNAME") or "user" */
  char  *  gr_name;   /* getenv("GROUP") or "dos" */
  char  *  gr_passwd; /* "" */
@};
@end example

@subheading Return Value

The next structure, or @code{NULL} at the end of the list.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example

struct group *g;
setgrent();
while ((g = getgrent()) != NULL)
@{
  printf("group %s gid %d\n", g->gr_name, g->gr_gid);
@}
endgrent();
@end example

@c -----------------------------------------------------------------------------
@node getgrgid, getgrnam, getgrent, Alphabetical List
@unnumberedsec getgrgid
@c From file ./posix/grp/getgrent.txh
@findex getgrgid
@subheading Syntax

@example
#include <grp.h>

extern struct group *getgrgid(int gid);
@end example

@subheading Description

This function returns the group entry that matches @var{gid}. 
@xref{getgrent}, for the description of @code{struct group}.

@subheading Return Value

The matching group, or @code{NULL} if none match.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node getgrnam, getgroups, getgrgid, Alphabetical List
@unnumberedsec getgrnam
@c From file ./posix/grp/getgrent.txh
@findex getgrnam
@subheading Syntax

@example
#include <grp.h>

struct group *getgrnam(char *name);
@end example

@subheading Description

This function returns the group entry for the group named @var{name}. 
@xref{getgrent}, for the description of @code{struct group}.

@subheading Return Value

The matching group, or @code{NULL} if none match.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node getgroups, gethostname, getgrnam, Alphabetical List
@unnumberedsec getgroups
@c From file ./posix/unistd/getgroup.txh
@findex getgroups
@subheading Syntax

@example
#include <unistd.h>

int getgroups(int size, gid_t *grouplist);
@end example

@subheading Description

This function always returns zero. It exists to assist porting from Unix.

@subheading Return Value

Zero.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node gethostname, getitimer, getgroups, Alphabetical List
@unnumberedsec gethostname
@c From file ./compat/unistd/gethostn.txh
@findex gethostname
@vindex HOSTNAME@r{ environment variable}
@subheading Syntax

@example
#include <unistd.h>
#include <sys/param.h>

int gethostname (char *buf, int size);
@end example

@subheading Description

Get the name of the host the program is executing on.  This name
is obtained from the network software, if present, otherwise from
the @code{"HOSTNAME"} environment variable, if present, finally
defaulting to @code{"pc"}.

The call fails if more than @var{size} characters are required to
specify the host name.  A buffer size of @code{MAXGETHOSTNAME} is
guaranteed to be enough.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char *buf = (char *) malloc (MAXGETHOSTNAME);
if (buf && 0 == gethostname (buf, MAXGETHOSTNAME))
  printf ("We're on %s\n", buf);
if (buf) free(buf);
@end example

@c -----------------------------------------------------------------------------
@node getitimer, getkey, gethostname, Alphabetical List
@unnumberedsec getitimer
@c From file ./posix/signal/itimer.txh
@findex getitimer
@subheading Syntax

@example
#include <sys/time.h>

int getitimer(int which, struct itimerval *value);
@end example

@subheading Description

This function gets the current value of the interval timer specified by
@var{which} into structure @var{value}.  Variable @var{which} can have
the value of @code{ITIMER_REAL} or @code{ITIMER_PROF}.
@xref{setitimer}, for more details about timers.

Upon return, the @code{it_value} member of @var{value} will hold the
amount of time left until timer expiration, or zero if the timer has
expired or was stopped by a previous call to @code{setitimer}.  The
@code{it_interval} member will hold the interval between two successive
alarms as set by the last call to @code{setitimer} (but note that
interval values less than the system clock granularity are rounded up to
that granularity).  The value returned in @code{it_interval} member is
@emph{not} set to zero when the timer is stopped, it always retains the
interval that was last in use.

@subheading Return Value

Returns 0 on success, -1 on failure (and sets @code{errno}).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node getkey, getlogin, getitimer, Alphabetical List
@unnumberedsec getkey
@c From file ./pc_hw/kb/getkey.txh
@findex getkey
@subheading Syntax

@example
#include <pc.h>
#include <keys.h>

int getkey(void);
@end example

@subheading Description

Waits for the user to press one key, then returns that key.  Alt-key
combinations have 0x100 added to them.  Extended keys return their
non-extended codes. 

The file @file{keys.h} has symbolic names for many of the keys.

@xref{getxkey}.

@subheading Return Value

The key pressed.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
while (getkey() != K_Alt_3)
  do_something();
@end example

@c -----------------------------------------------------------------------------
@node getlogin, getlongpass, getkey, Alphabetical List
@unnumberedsec getlogin
@c From file ./posix/unistd/getlogin.txh
@findex getlogin
@vindex USERNAME@r{ environment variable, and the user's login ID}
@vindex LOGNAME@r{ environment variable, and the user's login ID}
@vindex USER@r{ environment variable, and the user's login ID}
@subheading Syntax

@example
#include <unistd.h>

char *getlogin(void);
@end example

@subheading Description

Get the login ID of the user.

@subheading Return Value

Returns the value of the @code{USERNAME} environment variable if it is
defined, else the @code{LOGNAME} environment variable, else the
@code{USER} environment variable, else @code{"dosuser"}.

@code{USERNAME} is set automatically by Windows NT and Windows 2000.
None of these environment variables are set automatically on DOS,
Windows 95 or Windows 98.

The stock version of the file @file{DJGPP.ENV} defines @code{USER} with
the value @code{"dosuser"}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
printf("I am %s\n", getlogin());
@end example

@c -----------------------------------------------------------------------------
@node getlongpass, getmntent, getlogin, Alphabetical List
@unnumberedsec getlongpass
@c From file ./compat/stdlib/getlongp.txh
@findex getlongpass
@subheading Syntax

@example
#include <stdlib.h>

int  getlongpass(const char *prompt, char *password, int max_length)
@end example

@subheading Description

This function reads up to a Newline (CR or LF) or EOF (Ctrl-D or Ctrl-Z)
from the standard input, without an echo, after prompting with a
null-terminated string @var{prompt}.  It puts a null-terminated string of
at most @var{max_length - 1} first characters typed by the user into a
buffer pointed to by @var{password}.  Pressing Ctrl-C or Ctrl-Break will
cause the calling program to @code{exit(1)}. 

@subheading Return Value
  
Zero if successful, -1 on error (and @code{errno} is set to an
appropriate value).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char password[MAX_PASS];

(void)getlongpass("Password: ", password, MAX_PASS);
@end example

@c -----------------------------------------------------------------------------
@node getmntent, getopt, getlongpass, Alphabetical List
@unnumberedsec getmntent
@c From file ./compat/mntent/mntent.txh
@findex getmntent
@tindex mntent@r{ structure}
@subheading Syntax

@example
#include <mntent.h>

struct mntent *getmntent(FILE *filep);
@end example

@subheading Description

This function returns information about the various drives that are
available to your program.  Beginning with drive @file{A:}, information
is retrieved for successive drives with successive calls to
@code{getmntent}.  Note that drives @file{A:} and @file{B:} will only be
returned if there is an MS-DOS formatted disk in the drive; empty drives
are skipped.  For systems with a single floppy drive, it is returned as
if it were mounted on @file{A:/} or @file{B:/}, depending on how it was
last referenced (and if there is a disk in the drive).

The argument @var{filep} should be a @code{FILE*} pointer returned by
@code{setmntent} (@pxref{setmntent}).

For each drive scanned, a pointer to a static structure of the following
type is returned:

@example
struct mntent
@{
    char * mnt_fsname;  /* The name of this file system */
    char * mnt_dir;     /* The root directory of this file system */
    char * mnt_type;	/* Filesystem type */
    char * mnt_opts;    /* Options, see below */
    int    mnt_freq;    /* -1 */
    int    mnt_passno;  /* -1 */
    long   mnt_time;    /* -1 */
@};
@end example

DJGPP implementation returns the following in the first 4 fields of
@code{struct mntent}:

@table @code

@item mnt_fsname

For networked and CD-ROM drives, this is the name of root directory in
the form @file{\\HOST\PATH} (this is called a @dfn{UNC name}).

For drives compressed with DoubleSpace, @code{mnt_fsname} is the string
@file{@var{X}:\DBLSPACE.@var{NNN}}, where @var{X} is the drive letter of
the host drive and @var{NNN} is the sequence number of the Compressed
Volume File.

For drives compressed with Stacker, @code{mnt_fsname} is the string
@file{@var{X}:\STACVOL.@var{NNN}}, where @var{X} and @var{NNN} are as
for DoubleSpace drives.

For drives compressed with Jam (a shareware disk compression software),
@code{mnt_fsname} is the full name of the Jam archive file.

For SUBSTed drives, @code{mnt_fsname} is the actual directory name that
that was SUBSTed to emulate a drive.

JOINed drives get their @code{mnt_fsname} as if they were NOT JOINed
(i.e., either the label name or the default @samp{Drive @var{X}:}).

For drives with a volume label, @code{mnt_fsname} is the name of the
label; otherwise the string @samp{Drive @var{X}:}, where @var{X} is the
drive letter.

@item mnt_dir

For most drives, this is the name of its root directory @file{@var{X}:/}
(where @var{X} is the drive letter), except that JOINed drives get
@code{mnt_dir} as the name of the directory to which they were JOINed.

For systems with a single floppy drive (which can be referenced as either
@file{a:/} or @file{b:/}), the mount directory will be returned as one
of these, depending on which drive letter was last used to reference
that drive.

@item mnt_type

@example
 "fd"     for floppy disks
 "hd"     for hard disks
 "dblsp"  for disks compressed with DoubleSpace
 "stac"   for disks compressed with Stacker
 "jam"    for disks compressed with Jam
 "cdrom"  for CD-ROM drives
 "ram"    for RAM disks
 "subst"  for SUBSTed directories
 "join"   for JOINed disks
 "net"    for networked drives
@end example

@item mnt_opts

The string @samp{ro,dev=@var{XX}} for CD-ROM drives,
@samp{rw,dev=@var{XX}} for all the others, where @var{XX} is the
hexadecimal drive number of the REAL drive on which this filesystem
resides.  That is, if you call @code{stat} on @var{mnt_fsname}, you will
get the numeric equivalent of @var{XX} in @code{st_dev} member of
@code{struct stat}.  E.g., for drive @file{C:} you will get
@samp{rw,dev=02}.  Note that SUBSTed and JOINed drives get the drive
numbers as if SUBST and JOIN were @strong{not} in effect.

@end table

@subheading Return Value

This function returns a pointer to a @code{struct mntent}, or
@code{NULL} if there are no more drives to report on.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
struct mntent *m;
FILE *f;
f = setmntent("/etc/mnttab", "r");
while ((m = getmntent(f)))
  printf("Drive %s, name %s\n", m->mnt_dir, m->mnt_fsname);
endmntent(f);
@end example

@c -----------------------------------------------------------------------------
@node getopt, getpagesize, getmntent, Alphabetical List
@unnumberedsec getopt
@c From file ./posix/unistd/getopt.txh
@findex getopt
@subheading Syntax

@example
#include <unistd.h>

int getopt(int argc, char * const *argv, const char *options);
extern char *optarg;
extern int optind, opterr, optopt;
@end example

@subheading Description

Parse options from the command line.  @var{options} is a string of
valid option characters.  If a given option takes an argument, that
character should be followed by a colon.

For each valid switch, this function sets @code{optarg} to the argument
(if the switch takes one), sets @code{optind} to the index in @var{argv}
that it is using, sets @code{optopt} to the option letter found, and
returns the option letter found.

If an unexpected option is found, a question mark (@samp{?}) is returned.  
If an option argument is missing, a colon (@samp{:}) is returned if the
first character in @var{options} is a colon, otherwise a question mark is
returned.  In both cases, if @code{opterr} is nonzero and the first character
in @var{options} is not a colon, an error message is printed to
@code{stderr}.

The example below shows how @samp{?} can still be used as an option
(e.g., to request a summary of program usage) in addition to flagging
an unexpected option and a missing argument.

@subheading Return Value

The option character is returned when found.  -1 is returned when there are no
more options.  A colon (@samp{:}) is returned when an option argument is
missing and the first character in @var{options} is a colon.  A question mark
(@samp{?}) is returned when an invalid option is found or an option argument
is missing and the first character in @var{options} is not a colon.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
int c;
opterr = 0;
while ((c=getopt(argc, argv, ":?vbf:")) != -1)
@{
  switch (c)
  @{
    case 'v':
      verbose_flag ++;
      break;
    case 'b':
      binary_flag ++;
      break;
    case 'f':
      output_filename = optarg;
      break;
    case ':':
      printf("Missing argument %c\n", optopt);
      usage();
      exit(1);
    case '?':
      if (optopt == '?') @{
        usage();
        exit(0);
     @} else @{
        printf("Unknown option %c\n", optopt);
        usage();
        exit(1);
     @}
  @}
@}
@end example
@c -----------------------------------------------------------------------------
@node getpagesize, getpass, getopt, Alphabetical List
@unnumberedsec getpagesize
@c From file ./compat/unistd/getstubs.txh
@findex getpagesize
@subheading Syntax

@example
#include <unistd.h>

int getpagesize(void);
@end example

@subheading Description

Return the size of the native virtual memory page size.

@subheading Return Value

4096 for the i386 and higher processors.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node getpass, getpgrp, getpagesize, Alphabetical List
@unnumberedsec getpass
@c From file ./compat/stdlib/getpass.txh
@findex getpass
@subheading Syntax

@example
#include <stdlib.h>

char * getpass(const char *prompt)
@end example

@subheading Description

This function reads up to a Newline (CR or LF) or EOF (Ctrl-D or Ctrl-Z)
from the standard input, without an echo, after prompting with a
null-terminated string @var{prompt}.  It returns the string of at most 8
characters typed by the user.  Pressing Ctrl-C or Ctrl-Break will cause
the calling program to @code{exit(1)}.

@subheading Return Value
  
A pointer to a static buffer which holds the user's response.  The buffer
will be overwritten by each new call.  In case of any error in the lower
I/O routines, a NULL pointer will be returned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char *password = getpass("Password: ");
@end example
@c -----------------------------------------------------------------------------
@node getpgrp, getpid, getpass, Alphabetical List
@unnumberedsec getpgrp
@c From file ./posix/unistd/getpgrp.txh
@findex getpgrp
@subheading Syntax

@example
#include <unistd.h>

int getpgrp(void);
@end example

@subheading Description

Gets the process group, which is currently the same as the pid.

@subheading Return Value

The process group.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node getpid, getppid, getpgrp, Alphabetical List
@unnumberedsec getpid
@c From file ./posix/unistd/getpid.txh
@findex getpid
@subheading Syntax

@example
#include <unistd.h>

int getpid(void);
@end example

@subheading Description

Get the process ID, which uniquely identifies each program running on
the system. 

@subheading Return Value

The process ID.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node getppid, getpwent, getpid, Alphabetical List
@unnumberedsec getppid
@c From file ./posix/unistd/getppid.txh
@findex getppid
@subheading Syntax

@example
#include <unistd.h>

int getppid(void);
@end example

@subheading Description

Get the parent process ID.  Currently this is always 1, indicating that
the parent process is no longer running. 

@subheading Return Value

The parent process ID.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node getpwent, getpwnam, getppid, Alphabetical List
@unnumberedsec getpwent
@c From file ./posix/pwd/pwent.txh
@findex getpwent
@tindex passwd@r{ structure}
@vindex HOME@r{ environment variable, and password file entries}
@vindex SHELL@r{ environment variable, and password file entries}
@vindex COMSPEC@r{ environment variable, and password file entries}
@subheading Syntax

@example
#include <pwd.h>

struct passwd *getpwent(void);
@end example

@subheading Description

This function retrieves the next available password file entry. 
For MS-DOS, this is simulated by providing exactly one entry:

@example
struct passwd @{
  char * pw_name;    /* getlogin() */
  int    pw_uid;     /* getuid() */
  int    pw_gid;     /* getgid() */
  char * pw_dir;     /* "/" or getenv("HOME") */
  char * pw_shell;   /* "/bin/sh" or getenv("SHELL") */
  char * pw_gecos;   /* getlogin() */
  char * pw_passwd;  /* "" */
@};
@end example

The @code{pw_name} and @code{pw_gecos} members are returned as described
under @code{getlogin} (@pxref{getlogin}).  The @code{pw_uid} member is
returned as described under @code{getuid} (@pxref{getuid}).  @code{pw_gid}
is returned as described under @code{getgid} (@pxref{getgid}).  The
@code{pw_passwd} member is set to the empty string.  The @code{pw_dir}
member is set to the value of the environment variable @code{HOME} if it
is defined, or to @file{/} otherwise.  @code{pw_shell} is set as
follows:

@itemize @bullet
@item
If the environment variable @code{SHELL} is set, the value of
@code{SHELL}.

@item
If @code{SHELL} is not set, but the environment variable @code{COMSPEC} is,
the value of @code{COMSPEC}.

@item
If neither of the above variables is defined, @code{pw_shell} is set to
@code{"sh"}.
@end itemize

@subheading Return Value

The next passwd entry, or @code{NULL} if there are no more.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
struct passwd *p;
setpwent();
while ((p = getpwent()) != NULL)
@{
  printf("user %s name %s\n", p->pw_name, p->pw_gecos);
@}
endpwent();
@end example

@c -----------------------------------------------------------------------------
@node getpwnam, getpwuid, getpwent, Alphabetical List
@unnumberedsec getpwnam
@c From file ./posix/pwd/getpwnam.txh
@findex getpwnam
@subheading Syntax

@example
#include <pwd.h>

struct passwd *getpwnam(const char *name);
@end example

@subheading Description

This function gets the password file entry matching @var{name}.  See
@ref{getpwent}, for the description of @code{struct passwd}.

@subheading Return Value

The matching record, or @code{NULL} if none match.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node getpwuid, getrlimit, getpwnam, Alphabetical List
@unnumberedsec getpwuid
@c From file ./posix/pwd/getpwuid.txh
@findex getpwuid
@subheading Syntax

@example
#include <pwd.h>

struct passwd *getpwuid(uid_t uid);
@end example

@subheading Description

This function gets the password file entry matching @var{uid}.  See
@ref{getpwent}, for the description of @code{struct passwd}.

@subheading Return Value

The matching record, or @code{NULL} if none match.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node getrlimit, getrusage, getpwuid, Alphabetical List
@unnumberedsec getrlimit
@c From file ./compat/sys/resource/gtrlimit.txh
@findex getrlimit
@tindex rlimit@r{ structure}
@subheading Syntax

@example
#include <sys/resource.h>

int getrlimit (int rltype, struct rlimit *rlimitp);
@end example

@subheading Description

This function gets the resource limit specified by @var{rltype} and
stores it in the buffer pointed to by @var{rlimitp}.  The @code{rlimit}
structure is defined on @file{sys/resource.h} as follows:

@example
struct rlimit @{
  rlim_t rlim_cur;  /* current (soft) limit */
  rlim_t rlim_max;  /* maximum value for rlim_cur */
@};
@end example

The following resource types can be passed in @var{rltype}:

@table @code
@item RLIMIT_CPU
CPU time in milliseconds.

@item RLIMIT_FSIZE
Maximum file size.

@item RLIMIT_DATA
Data size.

@item RLIMIT_STACK
Stack size.

@item RLIMIT_CORE
Core file size.

@item RLIMIT_RSS
Resident set size.

@item RLIMIT_MEMLOCK
Locked-in-memory address space.

@item RLIMIT_NPROC
Number of processes.

@item RLIMIT_NOFILE
Number of open files.
@end table

Currently, only the @code{RLIMIT_STACK} and @code{RLIMIT_NOFILE} are
meaningful: the first returns the value of @code{_stklen}
(@pxref{_stklen}), the second the value returned by
@code{sysconf(_SC_OPEN_MAX)} (@pxref{sysconf}).  All other members of
the @code{rlimit} structure are set to @code{RLIM_INFINITY}, defined in
@file{sys/resource.h} as @code{2^31 - 1}.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
struct rlimit rlimitbuf;
int rc = getrlimit (RLIMIT_STACK, &rlimitbuf);
@end example


@c -----------------------------------------------------------------------------
@node getrusage, gets, getrlimit, Alphabetical List
@unnumberedsec getrusage
@c From file ./compat/sys/resource/resource.txh
@findex getrusage
@tindex rusage@r{ structure}
@subheading Syntax

@example
#include <sys/time.h>
#include <sys/resource.h>

int getrusage(int who, struct rusage *rusage);
@end example

@subheading Description

This function returns information about the running process.  The
structure @code{struct rusage} is defined on @code{<sys/resource.h>} as
follows:

@example
  struct rusage @{
    struct timeval ru_utime;	/* user time used */
    struct timeval ru_stime;	/* system time used */
    long ru_maxrss;		/* integral max resident set size */
    long ru_ixrss;		/* integral shared text memory size */
    long ru_idrss;		/* integral unshared data size */
    long ru_isrss;		/* integral unshared stack size */
    long ru_minflt;		/* page reclaims */
    long ru_majflt;		/* page faults */
    long ru_nswap;		/* swaps */
    long ru_inblock;		/* block input operations */
    long ru_oublock;		/* block output operations */
    long ru_msgsnd;		/* messages sent */
    long ru_msgrcv;		/* messages received */
    long ru_nsignals;		/* signals received */
    long ru_nvcsw;		/* voluntary context switches */
    long ru_nivcsw;		/* involuntary context switches */
  @};
@end example

Currently, the only field that is computed is @code{ru_utime}.  It is
computed as the total elapsed time used by the calling program.  The
remainder of the fields are set to zero.

The @var{who} parameter must be @code{RUSAGE_SELF} or
@code{RUSAGE_CHILDREN}. 

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
struct rusage r;
getrusage(RUSAGE_SELF, &r);
@end example

@c -----------------------------------------------------------------------------
@node gets, gettext, getrusage, Alphabetical List
@unnumberedsec gets
@c From file ./ansi/stdio/gets.txh
@findex gets
@subheading Syntax

@example
#include <stdio.h>

char *gets(char *buffer);
@end example

@subheading Description

Reads characters from @code{stdin}, storing them in @var{buffer}, until
either end of file or a newline is encountered.  If any characters were
stored, the @var{buffer} is then @code{NULL} terminated and its address
is returned, else @code{NULL} is returned.

@subheading Return Value

The address of the buffer, or @code{NULL}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
char buf[1000];
while (gets(buf))
  puts(buf);
@end example

@c -----------------------------------------------------------------------------
@node gettext, gettextinfo, gets, Alphabetical List
@unnumberedsec gettext
@c From file ./pc_hw/co80/conio.txh
@findex gettext
@subheading Syntax

@example
#include <conio.h>

int     gettext(int _left, int _top, int _right, int _bottom,
                void *_destin);
@end example

@subheading Description

Retrieve a block of screen characters into a buffer.
@code{gettext} is a macro defined in @code{conio.h} that will expand
into @code{_conio_gettext} (@pxref{_conio_gettext}). This is needed
to resolve the name conflict existing between the @code{gettext} function
from @code{libintl.a} defined in @code{libintl.h} and this one defined
in @code{conio.h}.
If you want to use both @code{gettext} functions in the same source file
you must use @code{_conio_gettext} (@pxref{_conio_gettext})
to get the @code{gettext} function from @code{conio.h}.
This means that if both headers are included in the same source file the
@code{gettext} keyword will always be reserved for the @code{gettext} function
defined in @code{libintl.h} and indeed will always make reference to the
@code{gettext} function from @code{libintl.a}.

@subheading Return Value

1

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node gettextinfo, gettime, gettext, Alphabetical List
@unnumberedsec gettextinfo
@c From file ./pc_hw/co80/conio.txh
@findex gettextinfo
@tindex text_info@r{ structure}
@subheading Syntax

@example
#include <conio.h>

void    gettextinfo(struct text_info *_r);
@end example

@subheading Description

This function returns the parameters of the current window on the
screen.  The return structure is this:

@example
struct text_info @{
    unsigned char winleft;
    unsigned char wintop;
    unsigned char winright;
    unsigned char winbottom;
    unsigned char attribute;
    unsigned char normattr;
    unsigned char currmode;
    unsigned char screenheight;
    unsigned char screenwidth;
    unsigned char curx;
    unsigned char cury;
@};
@end example

The @code{normattr} field is the text attribute which was in effect
before the program started.
@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node gettime, gettimeofday, gettextinfo, Alphabetical List
@unnumberedsec gettime
@c From file ./dos/dos/gettime.txh
@findex gettime
@tindex time@r{ structure}
@subheading Syntax

@example
#include <dos.h>

void gettime(struct time *);
@end example

@subheading Description

This function gets the current time.  The return structure is as follows:

@example
struct time @{
  unsigned char ti_min;
  unsigned char ti_hour;
  unsigned char ti_hund;
  unsigned char ti_sec;
@};
@end example

@xref{settime}. @xref{getdate}.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
struct time t;
gettime(&t);
@end example

@c -----------------------------------------------------------------------------
@node gettimeofday, getuid, gettime, Alphabetical List
@unnumberedsec gettimeofday
@c From file ./dos/dos/gettimeo.txh
@findex gettimeofday
@tindex timeval@r{ structure}
@tindex timezone@r{ structure}
@subheading Syntax

@example
#include <time.h>

int gettimeofday(struct timeval *tp, struct timezone *tzp);
@end example

@subheading Description

Gets the current GMT time and the local timezone information.  The
return structures are as follows:

@example
struct timeval @{
  long tv_sec;  /* seconds since 00:00:00 GMT 1/1/1970 */
  long tv_usec; /* microseconds */
@};
struct timezone @{
  int tz_minuteswest; /* west of GMT */
  int tz_dsttime;     /* set if daylight saving time in affect */
@};
@end example

If either @var{tp} or @var{tzp} are @code{NULL}, that information is not
provided. 

Note that although this function returns microseconds for compatibility
reasons, the values are precise to less than 1/20 of a second only.
The underlying DOS function has 1/20 second granularity, as it is
calculated from the 55 ms timer tick count, so you won't get better than
that with gettimeofday().

@xref{settimeofday}.

@subheading Return Value

Zero on success, nonzero on failure.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node getuid, getw, gettimeofday, Alphabetical List
@unnumberedsec getuid
@c From file ./posix/unistd/getuid.txh
@findex getuid
@subheading Syntax

@example
#include <unistd.h>

int getuid(void);
@end example

@subheading Description

Returns the user ID.

@subheading Return Value

42


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node getw, getwd, getuid, Alphabetical List
@unnumberedsec getw
@c From file ./ansi/stdio/getw.txh
@findex getw
@subheading Syntax

@example
#include <stdio.h>

int getw(FILE *file);
@end example

@subheading Description

Reads a single 32-bit binary word in native format from @var{file}.
This function is provided for compatibility with other 32-bit
environments, so it reads a 32-bit @code{int}, not a 16-bit
@code{short}, like some 16-bit DOS compilers do.

@xref{putw}.

@subheading Return Value

The value read, or @code{EOF} for end-of-file or error.  Since
@code{EOF} is a valid integer, you should use @code{feof} or
@code{ferror} to detect this situation. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
int i = getw(stdin);
@end example

@c -----------------------------------------------------------------------------
@node getwd, getxkey, getw, Alphabetical List
@unnumberedsec getwd
@c From file ./compat/unistd/getwd.txh
@findex getwd
@subheading Syntax

@example
#include <unistd.h>

char *getwd(char *buffer);
@end example

@subheading Description

Get the current directory and put it in @var{buffer}.  The return value
includes the drive specifier. 

@subheading Return Value

@var{buffer} is returned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char buf[PATH_MAX];
getwd(buf);
@end example

@c -----------------------------------------------------------------------------
@node getxkey, glob, getwd, Alphabetical List
@unnumberedsec getxkey
@c From file ./pc_hw/kb/getxkey.txh
@findex getxkey
@subheading Syntax

@example
#include <pc.h>
#include <keys.h>

int getxkey(void);
@end example

@subheading Description

Waits for the user to press one key, then returns that key.  Alt-key
combinations have 0x100 added to them, and extended keys have 0x200
added to them. 

The file @file{keys.h} has symbolic names for many of the keys.

@xref{getkey}.

@subheading Return Value

The key pressed.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
while (getxkey() != K_EEnd)
  do_something();
@end example

@c -----------------------------------------------------------------------------
@node glob, globfree, getxkey, Alphabetical List
@unnumberedsec glob
@c From file ./posix/glob/glob.txh
@findex glob
@tindex glob_t@r{ type}
@vindex LFN@r{ environment variable, and file-name globbing}
@vindex FNCASE@r{ environment variable, and file-name globbing}
@subheading Syntax

@example
#include <glob.h>

int  glob(const char *pattern, int flags,
          int (*errfunc)(const char *epath, int eerrno), glob_t *pglob);
@end example

@subheading Description

This function expands a filename wildcard which is passed as
@var{pattern}.  The pattern may include these special characters:

@table @code

@item *

Matches zero of more characters.

@item ?

Matches exactly one character (any character).

@item [...]

Matches one character from a group of characters.  If the first
character is @code{!}, matches any character @emph{not} in the group.  A
group is defined as a list of characters between the brackets,
e.g. @code{[dkl_]}, or by two characters separated by @code{-} to
indicate all characters between and including these two.  For example,
@code{[a-d]} matches @code{a}, @code{b}, @code{c}, or @code{d}, and
@code{[!a-zA-Z0-9]} matches any character that is not alphanumeric. 

@item ...

Matches all the subdirectories, recursively (VMS aficionados,
rejoice!).

@item \

Causes the next character to not be treated as special.  For example,
@code{\[} matches a literal @samp{[}.  If @var{flags} includes
@code{GLOB_NOESCAPE}, this quoting is disabled and @samp{\} is handled
as a simple character. 

@end table

The variable @var{flags} controls certain options of the expansion
process.  Possible values for @var{flags} are as follows:

@table @code

@item GLOB_APPEND

Append the matches to those already present in the array
@code{pglob->gl_pathv}.  By default, @code{glob} discards all previous
contents of @code{pglob->gl_pathv} and allocates a new memory block for
it.  If you use @code{GLOB_APPEND}, @code{pglob} should point to a
structure returned by a previous call to @code{glob}.

@item GLOB_DOOFFS

Skip @code{pglob->gl_offs} entries in @code{gl_pathv} and put new
matches after that point.  By default, @code{glob} puts the new matches
beginning at @code{pglob->gl_pathv[0]}.  You can use this flag both with
@code{GLOB_APPEND} (in which case the new matches will be put after the
first @code{pglob->gl_offs} matches from previous call to @code{glob}),
or without it (in which case the first @code{pglob->gl_offs} entries in
@code{pglob->gl_pathv} will be filled by @code{NULL} pointers).

@item GLOB_ERR

Stop when an unreadable directory is encountered and call user-defined
function @var{errfunc}.  This cannot happen under DOS (and thus
@var{errfunc} is never used).

@item GLOB_MARK

Append a slash to each pathname that is a directory.

@item GLOB_NOCHECK

If no matches are found, return the pattern itself as the only match.
By default, @code{glob} doesn't change @code{pglob} if no matches are
found.

@item GLOB_NOESCAPE

Disable blackslash as an escape character.  By default, backslash quotes
special meta-characters in wildcards described above.

@item GLOB_NOSORT

Do not sort the returned list.  By default, the list is sorted
alphabetically.  This flag causes the files to be returned in the order
they were found in the directory.

@end table

Given the pattern and the flags, @code{glob} expands the pattern and
returns a list of files that match the pattern in a structure a pointer
to which is passed via @var{pglob}.  This structure is like this:

@example
typedef struct @{
  size_t gl_pathc;
  char **gl_pathv;
  size_t gl_offs;
@} glob_t;
@end example

In the structure, the @code{gl_pathc} field holds the number of
filenames in @code{gl_pathv} list; this includes the filenames produced
by this call, plus any previous filenames if @code{GLOB_APPEND} or
@code{GLOB_DOOFFS} were set in @var{flags}.  The list of matches is
returned as an array of pointers to the filenames; @code{gl_pathv} holds
the address of the array.  Thus, the filenames which match the pattern
can be accessed as @code{gl_pathv[0]}, @code{gl_pathv[1]}, etc.  If
@code{GLOB_DOOFFS} was set in @var{flags}, the new matches begin at
offset given by @code{gl_offs}.

@code{glob} allocates memory to hold the filenames.  This memory should be
freed by calling @code{globfree} (@pxref{globfree}).

@subheading Return Value

Zero on success, or one of these codes:

@table @code

@item GLOB_ABORTED

Not used in DJGPP implementation.

@item GLOB_NOMATCH

No files matched the given pattern.

@item GLOB_NOSPACE

Not enough memory to accommodate expanded filenames.

@item GLOB_ERR

Never happens on MSDOS, see above.

@end table

@subheading Notes

@code{glob} will not match names of volume labels.

On MSDOS, filenames are always matched case-insensitively.  On
filesystems that preserve letter-case in filenames (such as Windows 9x),
matches are case-insensitive unless the pattern includes uppercase
characters.

On MSDOS, the list of expanded filenames will be returned in lower case,
if all the characters of the pattern (except those between brackets
[...]) are lower-case; if some of them are upper-case, the expanded
filenames will be also in upper case.  On filesystems that preserve
letter-case in filenames, long filenames are returned as they are found
in the directory entry; DOS-style 8+3 filenames are returned as on MSDOS
(in lower case if the pattern doesn't include any upper-case letters, in
upper case otherwise).

When the environment variable @samp{LFN} is set to @kbd{n}, @code{glob}
behaves on Windows 9x exactly as it does on MSDOS.

Setting the environment variable @samp{FNCASE} to @kbd{y}, or setting
the @code{_CRT0_FLAG_PRESERVE_FILENAME_CASE} bit in the
@code{_crt0_startup_flags} variable (@pxref{_crt0_startup_flags})
suppresses any letter-case conversions in filenames and forces
case-sensitive filename matching.  @xref{_preserve_fncase}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example

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

/* Convert a wildcard pattern into a list of blank-separated
   filenames which match the wildcard.  */

char * glob_pattern(char *wildcard)
@{
  char *gfilename;
  size_t cnt, length;
  glob_t glob_results;
  char **p;

  glob(wildcard, GLOB_NOCHECK, 0, &glob_results);

  /* How much space do we need?  */
  for (p = glob_results.gl_pathv, cnt = glob_results.gl_pathc;
       cnt; p++, cnt--)
    length += strlen(*p) + 1;

  /* Allocate the space and generate the list.  */
  gfilename = (char *) calloc(length, sizeof(char));
  for (p = glob_results.gl_pathv, cnt = glob_results.gl_pathc;
       cnt; p++, cnt--)
    @{
      strcat(gfilename, *p);
      if (cnt > 1)
        strcat(gfilename, " ");
    @}

  globfree(&glob_results);
  return gfilename;
@}

@end example
@c -----------------------------------------------------------------------------
@node globfree, gmtime, glob, Alphabetical List
@unnumberedsec globfree
@c From file ./posix/glob/globfree.txh
@findex globfree
@subheading Syntax

@example
#include <glob.h>

void globfree(glob_t *pglob);
@end example

@subheading Description

Frees the memory associated with @var{pglob}, which should have been
allocated by a call to @code{glob} (@pxref{glob}).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node gmtime, gmtime_r, globfree, Alphabetical List
@unnumberedsec gmtime
@c From file ./ansi/time/ctime.txh
@findex gmtime
@tindex tm@r{ structure}
@subheading Syntax

@example
#include <time.h>

struct tm *gmtime(const time_t *tod);
@end example

@subheading Description

Converts the time represented by @var{tod} into a structure.

The return structure has this format:

@example
struct tm @{
  int    tm_sec;    /* seconds after the minute [0-60] */
  int    tm_min;    /* minutes after the hour [0-59] */
  int    tm_hour;   /* hours since 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 */
  long   tm_gmtoff; /* offset from GMT in seconds */
  char * tm_zone;   /* timezone abbreviation */
@};
@end example

The structure pointed to is static and will be overwritten with
each call to @code{gmtime}.
The structure should be copied if it needs to be preserved.
@xref{gmtime_r}, for an alternate interface that allows the caller
to provide the structure to be filled.

@xref{localtime}, for a similar function that returns the information
corrected for the local time zone instead of GMT.

@subheading Return Value

A pointer to a static structure which is overwritten with each call. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
time_t x;
struct tm *t;
time(&x);
t = gmtime(&x);
@end example

@c -----------------------------------------------------------------------------
@node gmtime_r, _go32_conventional_mem_selector, gmtime, Alphabetical List
@unnumberedsec gmtime_r
@c From file ./ansi/time/ctime.txh
@findex gmtime_r
@subheading Syntax

@example
#include <time.h>

struct tm *gmtime_r(const time_t * restrict tod, struct tm * restrict tptr);
@end example

@subheading Description

Converts the time represented by @var{tod} into
a broken down calendar time structure @var{tptr}.

@xref{gmtime}, for a description of type @code{struct tm}.

@xref{gmtime}, for an alternate ISO Standard interface.

@xref{localtime_r}, for a similar function that returns the information
corrected for the local time zone instead of GMT.

@subheading Return Value

A pointer to @var{tptr} containing the broken down calendar time.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
time_t x;
struct tm *t;
struct tm tm;
time(&x);
t = gmtime_r(&x, &tm);
@end example

@c -----------------------------------------------------------------------------
@node _go32_conventional_mem_selector, _go32_dpmi_allocate_dos_memory, gmtime_r, Alphabetical List
@unnumberedsec _go32_conventional_mem_selector
@c From file ./go32/godefv1.txh
@findex _go32_conventional_mem_selector
@subheading Syntax

@example
#include <go32.h>

u_short _go32_conventional_mem_selector();
@end example

@subheading Description

This function returns a selector which has a physical base address
corresponding to the beginning of conventional memory.  This selector
can be used as a parameter to @code{movedata} (@pxref{movedata}) to
manipulate memory in the conventional address space. 

@subheading Return Value

The selector.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
short blank_row_buf[ScreenCols()];
/* scroll screen */
movedata(_go32_conventional_mem_selector(), 0xb8000 + ScreenCols()*2,
         _go32_conventional_mem_selector(), 0xb8000,
         ScreenCols() * (ScreenRows()-1) * 2);
/* fill last row */
movedata(_go32_my_ds, (int)blank_row_buf,
         _go32_conventional_mem_selector(),
            0xb8000 + ScreenCols()*(ScreenRows()-1)*2,
          ScreenCols() * 2);
@end example

@c -----------------------------------------------------------------------------
@node _go32_dpmi_allocate_dos_memory, _go32_dpmi_allocate_iret_wrapper, _go32_conventional_mem_selector, Alphabetical List
@unnumberedsec _go32_dpmi_allocate_dos_memory
@c From file ./go32/gormem.txh
@findex _go32_dpmi_allocate_dos_memory
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_allocate_dos_memory(_go32_dpmi_seginfo *info);
@end example

@subheading Description

@xref{DPMI Overview}.

Allocate a part of the conventional memory area (the first 640K).  Set
the @code{size} field of @var{info} to the number of paragraphs
requested (this is (size in bytes + 15)/16), then call.  The
@code{rm_segment} field of @var{info} contains the segment of the
allocated memory. 

The memory may be resized with @code{_go32_dpmi_resize_dos_memory} and
must be freed with @code{_go32_dpmi_free_dos_memory}. 

If there isn't enough memory in the system, the @code{size} field of
@var{info} has the largest available size, and an error is returned. 

See also @ref{dosmemput}, and @ref{dosmemget}.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
_go32_dpmi_seginfo info;
info.size = (want_size+15) / 16;
_go32_dpmi_allocate_dos_memory(&info);
dosmemput(buffer, want_size, info.rm_segment*16);
_go32_dpmi_free_dos_memory(&info);
@end example

@c -----------------------------------------------------------------------------
@node _go32_dpmi_allocate_iret_wrapper, _go32_dpmi_allocate_real_mode_callback_iret, _go32_dpmi_allocate_dos_memory, Alphabetical List
@unnumberedsec _go32_dpmi_allocate_iret_wrapper
@c From file ./go32/gopint.txh
@findex _go32_dpmi_allocate_iret_wrapper
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_allocate_iret_wrapper(_go32_dpmi_seginfo *info);
@end example

@subheading Description

@xref{DPMI Overview}.

This function creates a small assembler function that handles the
overhead of servicing an interrupt.  To use, put the address of your
servicing function in the @code{pm_offset} field of @var{info} and call
this function.  The @code{pm_field} will get replaced with the address
of the wrapper function, which you pass to both
@code{_go32_dpmi_set_protected_mode_interrupt_vector} and
@code{_go32_dpmi_free_iret_wrapper}.

@strong{Warning!} Because of the way DPMI works, you may @emph{not}
@code{longjmp} out of an interrupt handler or perform any system calls
(such as @code{printf}) from within an interrupt handler.

Do not enable interrupts with @code{enable()} or @code{asm("sti")} in your function.

See also @ref{_go32_dpmi_set_protected_mode_interrupt_vector},
and @ref{_go32_dpmi_free_iret_wrapper}.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
_go32_dpmi_seginfo info;
info.pm_offset = my_handler;
_go32_dpmi_allocate_iret_wrapper(&info);
_go32_dpmi_set_protected_mode_interrupt_handler(0x75, &info);
@dots{}
_go32_dpmi_free_iret_wrapper(&info);
@end example

@c -----------------------------------------------------------------------------
@node _go32_dpmi_allocate_real_mode_callback_iret, _go32_dpmi_allocate_real_mode_callback_retf, _go32_dpmi_allocate_iret_wrapper, Alphabetical List
@unnumberedsec _go32_dpmi_allocate_real_mode_callback_iret
@c From file ./go32/gormcb.txh
@findex _go32_dpmi_allocate_real_mode_callback_iret
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_allocate_real_mode_callback_iret(
        _go32_dpmi_seginfo *info, _go32_dpmi_registers *regs
);
@end example

@subheading Description

@xref{DPMI Overview}.

This function allocates a "real-mode callback".  Fill in the
@code{pm_offset} field of @var{info} and call this function.  It will
fill in the @code{rm_segment} and @code{rm_offset} fields.  Any time a
real-mode program calls the real-mode address, your function gets
called.  The registers in effect will be stored in @var{regs}, which
should be a global, and will be passed to your function.  Any changes in
@var{regs} will be reflected back into real mode.  A wrapper will be
added to your function to simulate the effects of an @code{iret}
instruction, so this function is useful for trapping real-mode software
interrupts (like 0x1b - @kbd{Ctrl-@key{Break}} hit). 

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
_go32_dpmi_registers regs;

my_handler(_go32_dpmi_registers *r)
@{
  r->d.eax = 4;
@}

setup()
@{
  _go32_dpmi_seginfo info;
  _go32_dpmi_seginfo old_vector;
  _go32_dpmi_get_real_mode_interrupt_vector(0x84, &old_vector);
  info.pm_offset = my_handler;
  _go32_dpmi_allocate_real_mode_callback_iret(&info, &regs);
  _go32_dpmi_set_real_mode_interrupt_vector(0x84, &info);
  do_stuff();
  _go32_dpmi_set_real_mode_interrupt_vector(0x84, &old_vector);
  _go32_dpmi_free_real_mode_callback(&info);
@}
@end example

@c -----------------------------------------------------------------------------
@node _go32_dpmi_allocate_real_mode_callback_retf, _go32_dpmi_chain_protected_mode_interrupt_vector, _go32_dpmi_allocate_real_mode_callback_iret, Alphabetical List
@unnumberedsec _go32_dpmi_allocate_real_mode_callback_retf
@c From file ./go32/gormcb.txh
@findex _go32_dpmi_allocate_real_mode_callback_retf
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_allocate_real_mode_callback_retf(
        _go32_dpmi_seginfo *info, _go32_dpmi_registers *regs
);
@end example

@subheading Description

@xref{DPMI Overview}.

This function allocates a "real-mode callback".  Fill in the
@code{pm_offset} field of @var{info} and call this function.  It will
fill in the @code{rm_segment} and @code{rm_offset} fields.  Any time a
real-mode program calls the real-mode address, your function gets
called.  The registers in effect will be stored in @var{regs}, which
should be a global, and will be passed to your function.  Any changes in
@var{regs} will be reflected back into real mode.  A wrapper will be
added to your function to simulate the effects of a far return, such
as the callback for the packet driver receiver.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@xref{_go32_dpmi_allocate_real_mode_callback_iret}, for an example of
usage.

@c -----------------------------------------------------------------------------
@node _go32_dpmi_chain_protected_mode_interrupt_vector, _go32_dpmi_free_dos_memory, _go32_dpmi_allocate_real_mode_callback_retf, Alphabetical List
@unnumberedsec _go32_dpmi_chain_protected_mode_interrupt_vector
@c From file ./go32/gopint.txh
@findex _go32_dpmi_chain_protected_mode_interrupt_vector
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_chain_protected_mode_interrupt_vector(
        int vector, _go32_dpmi_seginfo *info
);
@end example

@subheading Description

@xref{DPMI Overview}.

This function is used to chain a protected mode interrupt.  It will
build a suitable wrapper that will call your function and then jump to
the next handler.  Your function need not perform any special handling.

@strong{Warning!} Because of the way DPMI works, you may @emph{not}
@code{longjmp} out of an interrupt handler or perform any system calls
(such as @code{printf}) from within an interrupt handler.

Do not enable interrupts with @code{enable()} or @code{asm("sti")} in your function.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@xref{_go32_dpmi_set_protected_mode_interrupt_vector}.

@c -----------------------------------------------------------------------------
@node _go32_dpmi_free_dos_memory, _go32_dpmi_free_iret_wrapper, _go32_dpmi_chain_protected_mode_interrupt_vector, Alphabetical List
@unnumberedsec _go32_dpmi_free_dos_memory
@c From file ./go32/gormem.txh
@findex _go32_dpmi_free_dos_memory
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_free_dos_memory(_go32_dpmi_seginfo *info);
@end example

@subheading Description

@xref{DPMI Overview}.

This function frees the conventional memory allocated by
@code{_go32_dpmi_allocate_real_mode_memory}.  You should pass it the
same structure as was used to allocate it. 

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
_go32_dpmi_seginfo info;
info.size = 100;
_go32_dpmi_allocate_dos_memory(&info);
_go32_dpmi_free_dos_memory(&info);
@end example

@c -----------------------------------------------------------------------------
@node _go32_dpmi_free_iret_wrapper, _go32_dpmi_free_real_mode_callback, _go32_dpmi_free_dos_memory, Alphabetical List
@unnumberedsec _go32_dpmi_free_iret_wrapper
@c From file ./go32/gopint.txh
@findex _go32_dpmi_free_iret_wrapper
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_free_iret_wrapper(_go32_dpmi_seginfo *info);
@end example

@subheading Description

@xref{DPMI Overview}.

This function frees the memory used by the wrapper created by
@code{_go32_dpmi_allocate_iret_wrapper}.  You should not free a wrapper
that is still in use.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@xref{_go32_dpmi_allocate_iret_wrapper}.
@c -----------------------------------------------------------------------------
@node _go32_dpmi_free_real_mode_callback, _go32_dpmi_get_free_memory_information, _go32_dpmi_free_iret_wrapper, Alphabetical List
@unnumberedsec _go32_dpmi_free_real_mode_callback
@c From file ./go32/gormcb.txh
@findex _go32_dpmi_free_real_mode_callback
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_free_real_mode_callback(_go32_dpmi_seginfo *info);
@end example

@subheading Description

@xref{DPMI Overview}.

This function frees the real-mode callbacks and wrappers allocated by
@code{_go32_dpmi_allocate_real_mode_callback_iret} and
@code{_go32_dpmi_allocate_real_mode_callback_retf}. 

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@xref{_go32_dpmi_allocate_real_mode_callback_iret}, for an example of
usage.

@c -----------------------------------------------------------------------------
@node _go32_dpmi_get_free_memory_information, _go32_dpmi_get_protected_mode_interrupt_vector, _go32_dpmi_free_real_mode_callback, Alphabetical List
@unnumberedsec _go32_dpmi_get_free_memory_information
@c From file ./go32/godefv1.txh
@findex _go32_dpmi_get_free_memory_information
@tindex _go32_dpmi_meminfo@r{ type}
@subheading Syntax

@example
#include <dpmi.h

int _go32_dpmi_get_free_memory_information(_go32_dpmi_meminfo *info);
@end example

@subheading Description

This function fills in the following structure:

@example
typedef struct @{
  u_long available_memory;
  u_long available_pages;
  u_long available_lockable_pages;
  u_long linear_space;
  u_long unlocked_pages;
  u_long available_physical_pages;
  u_long total_physical_pages;
  u_long free_linear_space;
  u_long max_pages_in_paging_file;
  u_long reserved[3];
@} _go32_dpmi_meminfo;
@end example

The only field that is guaranteed to have useful data is
@code{available_memory}.  Any unavailable field has -1 in it. 

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
int phys_mem_left()
@{
  _go32_dpmi_meminfo info;
  _go32_dpmi_get_free_memory_information(&info);
  if (info.available_physical_pages != -1)
    return info.available_physical_pages * 4096;
  return info.available_memory;
@}
@end example

@c -----------------------------------------------------------------------------
@node _go32_dpmi_get_protected_mode_interrupt_vector, _go32_dpmi_get_real_mode_interrupt_vector, _go32_dpmi_get_free_memory_information, Alphabetical List
@unnumberedsec _go32_dpmi_get_protected_mode_interrupt_vector
@c From file ./go32/gopvec.txh
@findex _go32_dpmi_get_protected_mode_interrupt_vector
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_get_protected_mode_interrupt_vector(
        int vector, _go32_dpmi_seginfo *info
);
@end example

@subheading Description

@xref{DPMI Overview}.

This function puts the selector and offset of the specified interrupt
vector into the @code{pm_selector} and @code{pm_offset} fields of
@var{info}.  This structure can be saved and later passed to
@code{_go32_dpmi_set_protected_mode_interrupt_vector} to restore
a vector.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@xref{_go32_dpmi_set_protected_mode_interrupt_vector}, for an example of
usage.

@c -----------------------------------------------------------------------------
@node _go32_dpmi_get_real_mode_interrupt_vector, _go32_dpmi_lock_code, _go32_dpmi_get_protected_mode_interrupt_vector, Alphabetical List
@unnumberedsec _go32_dpmi_get_real_mode_interrupt_vector
@c From file ./go32/gorvec.txh
@findex _go32_dpmi_get_real_mode_interrupt_vector
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_get_real_mode_interrupt_vector(
        int vector, _go32_dpmi_seginfo *info
);
@end example

@subheading Description

@xref{DPMI Overview}.

This function gets the real-mode interrupt vector specified into the
address in the @code{rm_segment} and @code{rm_offset} fields in
@var{info}.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@xref{_go32_dpmi_allocate_real_mode_callback_iret}, for an example of
usage.

@c -----------------------------------------------------------------------------
@node _go32_dpmi_lock_code, _go32_dpmi_lock_data, _go32_dpmi_get_real_mode_interrupt_vector, Alphabetical List
@unnumberedsec _go32_dpmi_lock_code
@c From file ./go32/gopint.txh
@findex _go32_dpmi_lock_code
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_lock_code( void *lockaddr, unsigned long locksize);
@end example

@subheading Description

Locks the given region of code, starting at @var{lockaddr} for
@var{locksize} bytes.  @var{lockaddr} is a regular pointer in
your program, such as the address of a function.

@subheading Return Value

0 if success, -1 if failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example

void my_handler()
@{
@}

void lock_my_handler()
@{
  _go32_dpmi_lock_code(my_handler,
                       (unsigned long)(lock_my_handler - my_handler));
@}
@end example

@c -----------------------------------------------------------------------------
@node _go32_dpmi_lock_data, _go32_dpmi_remaining_physical_memory, _go32_dpmi_lock_code, Alphabetical List
@unnumberedsec _go32_dpmi_lock_data
@c From file ./go32/gopint.txh
@findex _go32_dpmi_lock_data
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_lock_data( void *lockaddr, unsigned long locksize);
@end example

@subheading Description

Locks the given region of data, starting at @var{lockaddr} for
@var{locksize} bytes.  @var{lockaddr} is a regular pointer in
your program, such as the address of a variable.

@subheading Return Value

0 if success, -1 if failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example

int semaphore=0;

void lock_my_handler()
@{
  _go32_dpmi_lock_data(&semaphore, 4);
@}
@end example
@c -----------------------------------------------------------------------------
@node _go32_dpmi_remaining_physical_memory, _go32_dpmi_remaining_virtual_memory, _go32_dpmi_lock_data, Alphabetical List
@unnumberedsec _go32_dpmi_remaining_physical_memory
@c From file ./go32/goqmem.txh
@findex _go32_dpmi_remaining_physical_memory
@subheading Syntax

@example
#include <dpmi.h>

unsigned long _go32_dpmi_remaining_physical_memory(void);
@end example

@subheading Description

Returns the amount of physical memory that is still available in the
system. 

@subheading Return Value

The amount in bytes.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _go32_dpmi_remaining_virtual_memory, _go32_dpmi_resize_dos_memory, _go32_dpmi_remaining_physical_memory, Alphabetical List
@unnumberedsec _go32_dpmi_remaining_virtual_memory
@c From file ./go32/goqmem.txh
@findex _go32_dpmi_remaining_virtual_memory
@subheading Syntax

@example
#include <dpmi.h>

unsigned long _go32_dpmi_remaining_virtual_memory(void);
@end example

@subheading Description

Returns the amount of virtual memory that is still available in the
system. 

@subheading Return Value

The amount in bytes.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _go32_dpmi_resize_dos_memory, _go32_dpmi_set_protected_mode_interrupt_vector, _go32_dpmi_remaining_virtual_memory, Alphabetical List
@unnumberedsec _go32_dpmi_resize_dos_memory
@c From file ./go32/gormem.txh
@findex _go32_dpmi_resize_dos_memory
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_resize_dos_memory(_go32_dpmi_seginfo *info);
@end example

@subheading Description

@xref{DPMI Overview}.

The @var{info} structure is the same one used to allocate the memory. 
Fill in a new value for @code{size} and call this function.  If there is
not enough memory to satisfy the request, the largest size is filled in
to the @code{size} field, the memory is not resized, and this function
fails. 

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
_go32_dpmi_seginfo info;
info.size = 10;
_go32_dpmi_allocate_dos_memory(&info);
info.size = 20;
_go32_dpmi_resize_dos_memory(&info);
_go32_dpmi_free_dos_memory(&info);
@end example

@c -----------------------------------------------------------------------------
@node _go32_dpmi_set_protected_mode_interrupt_vector, _go32_dpmi_set_real_mode_interrupt_vector, _go32_dpmi_resize_dos_memory, Alphabetical List
@unnumberedsec _go32_dpmi_set_protected_mode_interrupt_vector
@c From file ./go32/gopvec.txh
@findex _go32_dpmi_set_protected_mode_interrupt_vector
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_set_protected_mode_interrupt_vector(
        int vector, _go32_dpmi_seginfo *info
);
@end example

@subheading Description

@xref{DPMI Overview}.

This function sets the protected mode interrupt vector specified to
point to the given function.  The @code{pm_offset} and
@code{pm_selector} fields of @var{info} must be filled in
(@pxref{_go32_my_cs}).  The following should be noted:

@itemize @bullet

@item

You may not @code{longjmp} out of an interrupt handler.

@item

You may not make any function calls that require system calls, such
as @code{printf}. 

@item

This function will not wrap the handler for you.  The
@code{_go32_dpmi_allocate_iret_wrapper} and
@code{_go32_dpmi_chain_protected_mode_interrupt_vector} functions can
wrap your function if you want.

@item

You must set the pm_selector field of @var{info}.  Use
@code{_go32_my_cs} to get a selector valid for your functions. 

@end itemize

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
volatile int tics = 0;

timer_handler()
@{
  tics++;
@}

int main()
@{
  _go32_dpmi_seginfo old_handler, new_handler;

  printf("grabbing timer interrupt\n");
  _go32_dpmi_get_protected_mode_interrupt_vector(8, &old_handler);
  
  new_handler.pm_offset = (int)tic_handler;
  new_handler.pm_selector = _go32_my_cs();
  _go32_dpmi_chain_protected_mode_interrupt_vector(8, &new_handler);

  getkey();

  printf("releasing timer interrupt\n");
  _go32_dpmi_set_protected_mode_interrupt_vector(8, &old_handler);

  return 0;
@}

@end example

@c -----------------------------------------------------------------------------
@node _go32_dpmi_set_real_mode_interrupt_vector, _go32_dpmi_simulate_fcall, _go32_dpmi_set_protected_mode_interrupt_vector, Alphabetical List
@unnumberedsec _go32_dpmi_set_real_mode_interrupt_vector
@c From file ./go32/gorvec.txh
@findex _go32_dpmi_set_real_mode_interrupt_vector
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_set_real_mode_interrupt_vector(
        int vector, _go32_dpmi_seginfo *info
);
@end example

@subheading Description

@xref{DPMI Overview}.

This function sets the real-mode interrupt vector specified to point to
the address in the @code{rm_segment} and @code{rm_offset} fields in
@var{info}.

@subheading Return Value

Zero on success, nonzero on failure.
@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@xref{_go32_dpmi_allocate_real_mode_callback_iret}, for an example of
usage.

@c -----------------------------------------------------------------------------
@node _go32_dpmi_simulate_fcall, _go32_dpmi_simulate_fcall_iret, _go32_dpmi_set_real_mode_interrupt_vector, Alphabetical List
@unnumberedsec _go32_dpmi_simulate_fcall
@c From file ./go32/godefv1.txh
@findex _go32_dpmi_simulate_fcall
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_simulate_fcall(_go32_dpmi_registers *regs);
@end example

@subheading Description

@xref{DPMI Overview}.

This function simulates a real-mode far call to a function that returns
with a far return.  The registers are set up from @var{regs}, including
@code{CS} and @code{IP}, which indicate the address of the call.  Any
registers the function modifies are reflected in @var{regs} on return.

If @code{SS} and @code{SP} are both zero, a small temporary stack is
used when in real mode.  If not, they are used @emph{as is}.  It's a good
idea to use @code{memset} to initialize the register structure before
using it.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
_go32_dpmi_registers r;
r.x.ax = 47;
r.x.cs = some_segment;
r.x.ip = some_offset;
r.x.ss = r.x.sp = 0;
_go32_dpmi_simulate_fcall(&r);
printf("returns %d\n", r.x.ax);
@end example

@c -----------------------------------------------------------------------------
@node _go32_dpmi_simulate_fcall_iret, _go32_dpmi_simulate_int, _go32_dpmi_simulate_fcall, Alphabetical List
@unnumberedsec _go32_dpmi_simulate_fcall_iret
@c From file ./go32/godefv1.txh
@findex _go32_dpmi_simulate_fcall_iret
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_simulate_fcall_iret(_go32_dpmi_registers *regs);
@end example

@subheading Description

@xref{DPMI Overview}.

This function simulates a real-mode far call to a function that returns
with an @code{iret} instruction.  The registers are set up from
@var{regs}, including @code{CS} and @code{IP}, which indicate the
address of the call.  Any registers the function modifies are reflected
in @var{regs} on return. 

If @code{SS} and @code{SP} are both zero, a small temporary stack is
used when in real mode.  If not, they are used @emph{as is}.  It's a good
idea to use @code{memset} to initialize the register structure before
using it.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
_go32_dpmi_registers r;
r.x.ax = 47;
r.x.cs = some_segment;
r.x.ip = some_offset;
r.x.ss = r.x.sp = 0;
_go32_dpmi_simulate_fcall_iret(&r);
printf("returns %d\n", r.x.ax);
@end example

@c -----------------------------------------------------------------------------
@node _go32_dpmi_simulate_int, _go32_info_block, _go32_dpmi_simulate_fcall_iret, Alphabetical List
@unnumberedsec _go32_dpmi_simulate_int
@c From file ./go32/godefv1.txh
@findex _go32_dpmi_simulate_int
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_simulate_int(int vector, _go32_dpmi_registers *regs);
@end example

@subheading Description

@xref{DPMI Overview}.

This function simulates a real-mode interrup.  The registers are set up from
@var{regs}, including @code{CS} and @code{IP}, which indicate the
address of the call.  Any registers the function modifies are reflected
in @var{regs} on return. 

If @code{SS} and @code{SP} are both zero, a small temporary stack is
used when in real mode.  If not, they are used @emph{as is}.  It's a good
idea to use @code{memset} to initialize the register structure before
using it.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
_go32_dpmi_registers r;
r.h.ah = 0x08;
r.h.dl = 0x80; /* drive C: */
r.x.ss = r.x.sp = 0;
_go32_dpmi_simulate_int(0x13, &r);
printf("disk is %d cyl, %d head, %d sect\n",
       r.h.ch | ((r.x.cl<<2)&0x300),
       r.h.dh, r.h.cl & 0x3f));
@end example

@c -----------------------------------------------------------------------------
@node _go32_info_block, _go32_interrupt_stack_size, _go32_dpmi_simulate_int, Alphabetical List
@unnumberedsec _go32_info_block
@c From file ./go32/infostrc.txh
@vindex _go32_info_block
@tindex Go32_Info_Block@r{ type}
@subheading Syntax

@example
#include <go32.h>

extern __Go32_Info_Block _go32_info_block;
@end example

@subheading Description

The go32 information block is a mechanism for @file{go32} to pass
information to the application.  Some of this information is generally
useful, such as the pid or the transfer buffer, while some is used
internally to @file{libc.a} only. 

The structure has this format:

@example
typedef struct @{
  unsigned long  size_of_this_structure_in_bytes;
  unsigned long  linear_address_of_primary_screen;
  unsigned long  linear_address_of_secondary_screen;
  unsigned long  linear_address_of_transfer_buffer;
  unsigned long  size_of_transfer_buffer;
  unsigned long  pid;
  unsigned char  master_interrupt_controller_base;
  unsigned char  slave_interrupt_controller_base;
  unsigned short selector_for_linear_memory;
  unsigned long  linear_address_of_stub_info_structure;
  unsigned long  linear_address_of_original_psp;
  unsigned short run_mode;
  unsigned short run_mode_info;
@} Go32_Info_Block;
@end example

The linear address fields provide values that are suitable for
@code{dosmemget}, @code{dosmemput}, and @code{movedata}.  The
selector_for_linear_memory is suitable for @code{<sys/farptr.h>}
selector parameters.

Due to the length of these fields, and their popularity, the following
macros are available:

@table @code

@item _dos_ds

This expands to _go32_info_block.selector_for_linear_memory

@item __tb

This expands to _go32_info_block.linear_address_of_transfer_buffer

@item __tb_size

This expands to _go32_info_block.size_of_transfer_buffer

@end table

The @code{run_mode} field indicates the mode that the program is running
in.  The following modes are defined:

@table @code

@item _GO32_RUN_MODE_UNDEF

This indicates that the extender did not (or could not) determine or
provide the mode information.  The most probable reason is that it's an
older extender that does not support this field.  The program should not
assume anything about the run mode if it is this value. 

@item _GO32_RUN_MODE_RAW

This indicates that no CPU manager is being used, and no XMS manager is
present.  The CPU is being managed directly from the extender, and
memory was allocated from the extended memory pool. 

@item _GO32_RUN_MODE_XMS

This indicates that the extender is managing the CPU, but an XMS driver
is managing the memory pool. 

@item _GO32_RUN_MODE_VCPI

This indicates that a VCPI server (like @code{emm386} or @code{qemm}) is
managing both the CPU and the memory. 

@item _GO32_RUN_MODE_DPMI

This indicates that a DPMI server (like @code{qdpmi} or Windows) is
managing both the CPU and memory.  Programs may rely on this value
to determine if it is safe to use DPMI 0.9 functions.

If this value is set, the @code{run_mode_info} field has the DPMI
specification version, in hex, shifted eight bits.  For example, DPMI
0.9 has 0x005A in the @code{run_mode_info} field. 

@end table

Note that the program should not assume that the value will be one of
the listed values.  If the program is running with an extender that
provides some other mode (say, a newly released extender) then the
program should be able to handle that case gracefully. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
dosmemget(_go32_info_block.linear_address_of_primary_screen,
          80*25*2, buf);
@end example

@c -----------------------------------------------------------------------------
@node _go32_interrupt_stack_size, _go32_my_cs, _go32_info_block, Alphabetical List
@unnumberedsec _go32_interrupt_stack_size
@c From file ./go32/gopint.txh
@vindex _go32_interrupt_stack_size
@subheading Syntax

@example
#include <dpmi.h>

extern unsigned long _go32_interrupt_stack_size;
@end example

@subheading Description

The default size of the interrupt handler's stack.  Defaults to 32k.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _go32_my_cs, _go32_my_ds, _go32_interrupt_stack_size, Alphabetical List
@unnumberedsec _go32_my_cs
@c From file ./go32/godefv1.txh
@findex _go32_my_cs
@subheading Syntax

@example
#include <go32.h>

u_short _go32_my_cs();
@end example

@subheading Description

Returns the current @code{CS}.  This is useful for setting up interrupt
vectors and such. 

@subheading Return Value

@code{CS}

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _go32_my_ds, _go32_my_ss, _go32_my_cs, Alphabetical List
@unnumberedsec _go32_my_ds
@c From file ./go32/godefv1.txh
@findex _go32_my_ds
@subheading Syntax

@example
#include <go32.h>

u_short _go32_my_ds();
@end example

@subheading Description

Returns the current @code{DS}.  This is useful for moving memory
and such. 

@subheading Return Value

@code{DS}

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _go32_my_ss, _go32_rmcb_stack_size, _go32_my_ds, Alphabetical List
@unnumberedsec _go32_my_ss
@c From file ./go32/godefv1.txh
@findex _go32_my_ss
@subheading Syntax

@example
#include <go32.h>

u_short _go32_my_ss();
@end example

@subheading Description

Returns the current @code{SS}.  This is useful for moving memory
and such. 

@subheading Return Value

@code{SS}

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _go32_rmcb_stack_size, _go32_want_ctrl_break, _go32_my_ss, Alphabetical List
@unnumberedsec _go32_rmcb_stack_size
@c From file ./go32/gormcb.txh
@vindex _go32_rmcb_stack_size
@subheading Syntax

@example
#include <dpmi.h>

extern unsigned long _go32_rmcb_stack_size;
@end example

@subheading Description

The default size of the real mode callback handler's stack.  Defaults to 32k.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _go32_want_ctrl_break, _go32_was_ctrl_break_hit, _go32_rmcb_stack_size, Alphabetical List
@unnumberedsec _go32_want_ctrl_break
@c From file ./go32/go32cbrk.txh
@findex _go32_want_ctrl_break
@subheading Syntax

@example
#include <go32.h>

void   _go32_want_ctrl_break(int yes);
@end example

@subheading Description

This function tells go32 whether or not it wants @kbd{Ctrl-Break} to be
an exception or passed to the application.  If you pass a nonzero value
for @var{yes}, pressing @kbd{Ctrl-Break} will set a flag that can be
detected with @code{_go32_was_ctrl_break_hit}
(@pxref{_go32_was_ctrl_break_hit}).  If you pass zero for @var{yes}, when
you press @kbd{Ctrl-Break} the program will be terminated. 

Note that if you call @code{_go32_was_ctrl_break_hit}, this function
automatically gets called to ask for @kbd{Ctrl-Break} events. 

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
_g32_want_ctrl_break(1);
do_something_long();
_g32_want_ctrl_break(0);
@end example

@c -----------------------------------------------------------------------------
@node _go32_was_ctrl_break_hit, gotoxy, _go32_want_ctrl_break, Alphabetical List
@unnumberedsec _go32_was_ctrl_break_hit
@c From file ./go32/go32cbrk.txh
@findex _go32_was_ctrl_break_hit
@subheading Syntax

@example
#include <go32.h>

unsigned _go32_was_ctrl_break_hit(void);
@end example

@subheading Description

This function returns the number of times that @kbd{Ctrl-Break} was hit
since the last call to this function or @code{_go32_want_ctrl_break}
(@pxref{_go32_want_ctrl_break}). 

@subheading Return Value

Zero if @kbd{Ctrl-Break} hasn't been hit, nonzero to indicate how many
times if it has been hit. 

Note that @code{_go32_want_ctrl_break} is automatically called to
request these events, so you don't have to set up for this call. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
while (!_go32_was_ctrl_break_hit())
  do_something();
@end example

@c -----------------------------------------------------------------------------
@node gotoxy, gppconio_init, _go32_was_ctrl_break_hit, Alphabetical List
@unnumberedsec gotoxy
@c From file ./pc_hw/co80/conio.txh
@findex gotoxy
@subheading Syntax

@example
#include <conio.h>

void gotoxy(int x, int y);
@end example

@subheading Description

Move the cursor to row y, column x.  The upper left corner of the
current window is (1,1).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node gppconio_init, __has_fd_properties, gotoxy, Alphabetical List
@unnumberedsec gppconio_init
@c From file ./pc_hw/co80/conio.txh
@findex gppconio_init
@subheading Syntax

@example
#include <conio.h>

void gppconio_init(void);
@end example

@subheading Description

Initialize the screen.  This is called automatically at program start-up
if you use any of the @code{conio} functions, but there may be
times when you need to call it again, typically after calling some video
BIOS function which affects screen parameters.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __has_fd_properties, _hash2v, gppconio_init, Alphabetical List
@unnumberedsec __has_fd_properties
@c From file ./dos/io/fd_props.txh
@findex __has_fd_properties
@subheading Syntax

@example
#include <libc/fd_props.h>

int __has_fd_properties(int fd);
@end example

@subheading Description

This internal function checks whether there are any properties associated
with the file descriptor @var{fd}.

@subheading Return Value

Non-zero if @var{fd} has any properties; zero otherwise.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _hash2v, hasmntopt, __has_fd_properties, Alphabetical List
@unnumberedsec _hash2v
@c From file ./posix/search/_hash2v.txh
@findex _hash2v
@subheading Syntax

@example
#include <search.h>

unsigned long _hash2v(unsigned char *s, unsigned long *v2)
@end example

@subheading Description

This function generate two hash values from the string @var{s}.  It
returns the first and sets *@var{v2} to the second.  

@subheading Return Value

The first hash value.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
#include <search.h>
#include <stdio.h>


int main(void)
@{
  unsigned int hash_value1, hash_value2;

  hash_value1 = _hash2v("", &hash_value2);
  printf("_hash2v generated the values 0x%08lx and 0x%08lx from \"\" (the empty string).\n",
         hash_value1, hash_value2);
  hash_value1 = _hash2v("a", &hash_value2);
  printf("_hash2v generated the values 0x%08lx and 0x%08lx from \"a\".\n"
         hash_value1, hash_value2);

  return 0;
@}

@end example

@c -----------------------------------------------------------------------------
@node hasmntopt, hcreate, _hash2v, Alphabetical List
@unnumberedsec hasmntopt
@c From file ./compat/mntent/mntent.txh
@findex hasmntopt
@subheading Syntax

@example
#include <mntent.h>

char *hasmntopt(const struct mntent *mnt, const char *opt);
@end example

@subheading Description

This function scans the @code{mnt_opts} field of the @code{mntent}
structure pointed to by @var{mnt} for a substring that matches
@var{opt}.  @xref{getmntent}.

@subheading Return Value

This function returns the address of the substring if a match is found,
or @code{NULL} otherwise.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node hcreate, hdestroy, hasmntopt, Alphabetical List
@unnumberedsec hcreate
@c From file ./posix/search/hcreate.txh
@findex hcreate
@subheading Syntax

@example
#include <search.h>

int hcreate(size_t nel)
@end example

@subheading Description

This function creates a hash table that has room for @var{nel}
elements.  

There can only be at most one hash table in use at any time.  

See also @code{hdestroy} (@pxref{hdestroy}) and @code{hsearch}
(@pxref{hsearch}).  

@subheading Return Value

Non-zero if successful, or zero if the hash table couldn't be
created.  

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
#include <search.h>
#include <stdio.h>

#define N_ELS	1000

int main(void)
@{

  if( hcreate(N_ELS) )
  @{
    printf("Hash table created successfully.\n");
  @}
  else
  @{
    printf("Failed to create hash table.\n");
  @}

  return 0;
@}

@end example

@c -----------------------------------------------------------------------------
@node hdestroy, highvideo, hcreate, Alphabetical List
@unnumberedsec hdestroy
@c From file ./posix/search/hcreate.txh
@findex hdestroy
@subheading Syntax

@example
#include <search.h>

void hdestroy(void)
@end example

@subheading Description

This function destroys the hash table previously created by
a call to @code{hcreate} (@pxref{hcreate}).  

See also @code{hsearch} (@pxref{hsearch}).  

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
#include <search.h>

#define N_ELS 10000

int main(void)
@{

  if( hcreate(N_ELS) )
  @{
    printf("Hash table created successfully.\n");

    /*
       Insert elements into the hash table and look them up.
       ...
     */

    hdestroy();
  @}
  else
  @{
    printf("Failed to create hash table.\n");
  @}

  return 0;
@}

@end example

@c -----------------------------------------------------------------------------
@node highvideo, hsearch, hdestroy, Alphabetical List
@unnumberedsec highvideo
@c From file ./pc_hw/co80/conio.txh
@findex highvideo
@subheading Syntax

@example
#include <conio.h>

void highvideo(void);
@end example

@subheading Description

Causes any new characters put on the screen to be bright.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node hsearch, htonl, highvideo, Alphabetical List
@unnumberedsec hsearch
@c From file ./posix/search/hcreate.txh
@findex hsearch
@tindex ACTION@r{ type}
@tindex ENTRY@r{ type}
@subheading Syntax

@example
#include <search.h>

ENTRY * hsearch(ENTRY item, ACTION action);
@end example

@subheading Description

This function searches the hash table previously created by a call to
@code{hcreate} (@pxref{hcreate}) for the key @var{item.key}.  If the
key is found a pointer to that entry is returned.  If the key is not
found and action is ENTER, @var{item} is added to the hash table and a
pointer to the newly added entry is returned.  If the key is not found
and action is FIND, @code{NULL} is returned.  

The comparison function used is @code{strcmp}.  

The types ACTION and ENTRY are defined as:

@example
typedef enum @{
  FIND,
  ENTER
@} ACTION;

typedef struct entry @{
  char    *key;
  void    *data;
@} ENTRY;
@end example

See also @code{hdestroy} (@pxref{hdestroy}).  

@subheading Return Value

@code{NULL} if action is ENTER but hash table is full.  
A pointer to the found or inserted item, if action is ENTER.  

A pointer to the found item or @code{NULL}, if action is FIND.  

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
#include <search.h>

#define N_ELS 10000

int main(void)
@{
  ENTRY item, *item_p;

  if( ! hcreate(N_ELS) )
  @{
    printf("Hash table could not be created.\n");
    return 1;
  @}

  /* Fill hash. */
  while( /* element to insert */ )
  @{
    item.key = /* allocate space for key and setting it */ 
    item.data = /* allocate space for data and setting it */
    item_p = hsearch(item, ENTER);
    if( ! item_p )
    @{
      printf("Out of memory.\n");
      return 1;
    @}
  @}

  /* Look up element. */
  item.key = /* some key */
  item_p = hsearch(item, FIND)
  if( item_p )
  @{
    printf("Found key '%s' with data pointing to %p.\n", item.key, item.data);
  @}
  else
  @{
    printf("Can't find key '%s'.\n", item.key);
  @}

  hdestroy();

  return 0;
@}

@end example
@c -----------------------------------------------------------------------------
@node htonl, htons, hsearch, Alphabetical List
@unnumberedsec htonl
@c From file ./pc_hw/endian/htonl.txh
@findex htonl
@subheading Syntax

@example
#include <netinet/in.h>

unsigned long htonl(unsigned long val);
@end example

@subheading Description

This function converts from host formatted longs to network formatted
longs.  For the i386 and higher processors, this means that the bytes
are swapped from 1234 order to 4321 order.

@subheading Return Value

The network-order value.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
packet.ipaddr = htonl(ip);
@end example
@c -----------------------------------------------------------------------------
@node htons, hypot, htonl, Alphabetical List
@unnumberedsec htons
@c From file ./pc_hw/endian/htons.txh
@findex htons
@subheading Syntax

@example
#include <netinet/in.h>

unsigned short htons(unsigned short val);
@end example

@subheading Description

This function converts from host formatted shorts to network formatted
shorts.  For the i386 and higher processors, this means that the bytes
are swapped from 12 order to 21 order.

@subheading Return Value

The network-order value.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
tcp.port = htons(port);
@end example


@c -----------------------------------------------------------------------------
@node hypot, imaxabs, htons, Alphabetical List
@unnumberedsec hypot
@c From file ./ansi/math/hypot.txh
@findex hypot
@subheading Syntax

@example
#include <math.h>

double hypot(double x, double y);
@end example

@subheading Description

This function computes @code{sqrt(@var{x}*@var{x} + @var{y}*@var{y})},
the length of a hypotenuse of a right triangle whose shorter sides are
@var{x} and @var{y}.  In other words, it computes the Euclidean distance
between the points @code{(0,0)} and @code{(@var{x},@var{y})}.  Since the
computation is done in extended precision, there is no danger of
overflow or underflow when squaring the arguments, whereas direct
computation of @code{sqrt(@var{x}*@var{x} + @var{y}*@var{y})} could
cause overflow or underflow for extreme (very large or very small)
values of @var{x} and @var{y}.

@subheading Return Value

The value of @code{sqrt(@var{x}*@var{x} + @var{y}*@var{y})}.  If both
arguments are finite, but the result is so large that it would overflow
a @code{double}, the return value is @code{Inf}, and @code{errno} is set
to @code{ERANGE}.  If one of the arguments is @code{Inf}, the return
value is @code{Inf} and the value of @code{errno} is left unchanged.  If
one of the arguments is @code{NaN}, the return value is @code{NaN} and
@code{errno} is set to @code{EDOM}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node imaxabs, imaxdiv, hypot, Alphabetical List
@unnumberedsec imaxabs
@c From file ./c99/inttypes/imaxabs.txh
@findex imaxabs
@subheading Syntax

@example
#include <inttypes.h>

intmax_t imaxabs (intmax_t x);
@end example

@subheading Description

This function takes the absolute value of @var{x}.

@code{abs} (@pxref{abs}) operates on an @code{int}.  This function
operates on a greatest-width integer.

@subheading Return Value

@code{|@var{x}|}

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable

@c -----------------------------------------------------------------------------
@node imaxdiv, inb, imaxabs, Alphabetical List
@unnumberedsec imaxdiv
@c From file ./c99/inttypes/imaxdiv.txh
@findex imaxdiv
@tindex imaxdiv_t@r{ type}
@subheading Syntax

@example
#include <inttypes.h>

imaxdiv_t imaxdiv (intmax_t numerator, intmax_t denominator);
@end example

@subheading Description

Returns the quotient and remainder of the division @var{numerator}
divided by @var{denominator}.  The return type is as follows:

@example
typedef struct @{
  intmax_t quot;
  intmax_t rem;
@} imaxdiv_t;
@end example

@subheading Return Value

The results of the division are returned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable


@subheading Example

@example
imaxdiv_t l = imaxdiv(42, 3);
printf("42 = %" PRIdMAX " x 3 + %" PRIdMAX "\n", l.quot, l.rem);

imaxdiv(+40, +3) = @{ +13, +1 @}
imaxdiv(+40, -3) = @{ -13, -1 @}
imaxdiv(-40, +3) = @{ -13, -1 @}
imaxdiv(-40, -3) = @{ +13, -1 @}

@end example
@c -----------------------------------------------------------------------------
@node inb, index, imaxdiv, Alphabetical List
@unnumberedsec inb
@c From file ./pc_hw/io/inb.txh
@findex inb
@subheading Syntax

@example
#include <pc.h>

unsigned char inb(unsigned short _port);
@end example

@subheading Description

Calls @ref{inportb}. Provided only for compatibility.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node index, initstate, inb, Alphabetical List
@unnumberedsec index
@c From file ./compat/bsd/index.txh
@findex index
@subheading Syntax

@example
#include <strings.h>

char *index(const char *string, int ch);
@end example

@subheading Description

Returns a pointer to the first occurrence of @var{ch} in @var{string}. 
Note that the @code{NULL} character counts, so if you pass zero as
@var{ch} you'll get a pointer to the end of the string back. 

@subheading Return Value

A pointer to the character, or @code{NULL} if it wasn't found.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
if (index(path, '*'))
  do_wildcards(path);
@end example

@c -----------------------------------------------------------------------------
@node initstate, inp, index, Alphabetical List
@unnumberedsec initstate
@c From file ./compat/stdlib/random.txh
@findex initstate
@subheading Syntax

@example
#include <stdlib.h>

char *initstate(unsigned seed, char *arg_state, int n);
@end example

@subheading Description

Initializes the random number generator (@pxref{random}) with pointer
@var{arg_state} to array of @var{n} bytes, then calls @code{srandom} with
@var{seed}.

@subheading Return Value

Pointer to old state information.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node inp, inportb, initstate, Alphabetical List
@unnumberedsec inp
@c From file ./pc_hw/io/inp.txh
@findex inp
@subheading Syntax

@example
#include <pc.h>

unsigned char inp(unsigned short _port);
@end example

@subheading Description

Calls @ref{inportb}.  Provided only for compatibility.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node inportb, inportl, inp, Alphabetical List
@unnumberedsec inportb
@c From file ./pc_hw/io/ib.txh
@findex inportb
@subheading Syntax

@example
#include <pc.h>

unsigned char inportb(unsigned short _port);
@end example

@subheading Description

Read a single 8-bit I/O port.

This function is provided as an inline assembler macro, and will be
optimized down to a single opcode when you optimize your program.

@subheading Return Value

The value returned through the port.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node inportl, inportsb, inportb, Alphabetical List
@unnumberedsec inportl
@c From file ./pc_hw/io/il.txh
@findex inportl
@subheading Syntax

@example
#include <pc.h>

unsigned long inportl(unsigned short _port);
@end example

@subheading Description

This function reads a single 32-bit I/O port.

This function is provided as an inline assembler macro, and will be
optimized down to a single opcode when you optimize your program.

@subheading Return Value

The value returned from the port.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node inportsb, inportsl, inportl, Alphabetical List
@unnumberedsec inportsb
@c From file ./pc_hw/io/isb.txh
@findex inportsb
@subheading Syntax

@example
#include <pc.h>

void inportsb(unsigned short _port, unsigned char *_buf, unsigned _len);
@end example

@subheading Description

Reads the 8-bit @var{_port} @var{_len} times, and stores the bytes in
@var{buf}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node inportsl, inportsw, inportsb, Alphabetical List
@unnumberedsec inportsl
@c From file ./pc_hw/io/isl.txh
@findex inportsl
@subheading Syntax

@example
#include <pc.h>

void inportsl(unsigned short _port, unsigned long *_buf, unsigned _len);
@end example

@subheading Description

Reads the 32-bit @var{_port} @var{_len} times, and stores the bytes in
@var{buf}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node inportsw, inportw, inportsl, Alphabetical List
@unnumberedsec inportsw
@c From file ./pc_hw/io/isw.txh
@findex inportsw
@subheading Syntax

@example
#include <pc.h>

void inportsw(unsigned short _port,
              unsigned short *_buf, unsigned _len);
@end example

@subheading Description

Reads the 16-bit @var{_port} @var{_len} times, and stores the bytes in
@var{buf}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node inportw, inpw, inportsw, Alphabetical List
@unnumberedsec inportw
@c From file ./pc_hw/io/iw.txh
@findex inportw
@subheading Syntax

@example
#include <pc.h>

unsigned short inportw(unsigned short _port);
@end example

@subheading Description

Read a single 16-bit I/O port.

This function is provided as an inline assembler macro, and will be
optimized down to a single opcode when you optimize your program.

@subheading Return Value

The value returned through the port.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node inpw, insline, inportw, Alphabetical List
@unnumberedsec inpw
@c From file ./pc_hw/io/inpw.txh
@findex inpw
@subheading Syntax

@example
#include <pc.h>

unsigned short inpw(unsigned short _port);
@end example

@subheading Description

Calls @ref{inportw}.  Provided only for compatibility.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node insline, insque, inpw, Alphabetical List
@unnumberedsec insline
@c From file ./pc_hw/co80/conio.txh
@findex insline
@subheading Syntax

@example
#include <conio.h>

void insline(void);
@end example

@subheading Description

A blank line is inserted at the current cursor position.  The previous
line and lines below it scroll down.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node insque, __install_dev_full, insline, Alphabetical List
@unnumberedsec insque
@c From file ./compat/search/insque.txh
@findex insque
@tindex qelem@r{ structure}
@subheading Syntax

@example
#include <search.h>

void insque(struct qelem *elem, struct qelem *pred);
@end example

@subheading Description

This function manipulates queues built from doubly linked lists.  Each element
in the queue must be in the form of @code{struct qelem} which is defined
thus:

@example
struct qelem @{
  struct qelem *q_forw;
  struct qelem *q_back;
  char q_data[0];
@}
@end example

This function inserts @var{elem} in a queue immediately after @var{pred}.


@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __install_dev_full, __install_dev_zero, insque, Alphabetical List
@unnumberedsec __install_dev_full
@c From file ./fsext/fse_zero.txh
@findex __install_dev_full

@subheading Syntax

@example
#include <sys/xdevices.h>

int __install_dev_full (void);
@end example

@subheading Description

This function activates support for the special file @file{/dev/full}.
When read, @file{dev/full} always returns @samp{\0} characters.  Writes
to @file{/dev/full} will fail with @code{errno} set to @code{ENOSPC}.
Seeks on @file{/dev/full} always succeed.

The DJGPP debug support functions will interfere with @file{/dev/full}
(@pxref{File System Extensions}).

@subheading Return Value

On success, a non-zero value is returned; on failure, zero is returned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable

@c -----------------------------------------------------------------------------
@node __install_dev_zero, int386, __install_dev_full, Alphabetical List
@unnumberedsec __install_dev_zero
@c From file ./fsext/fse_zero.txh
@findex __install_dev_zero

@subheading Syntax

@example
#include <sys/xdevices.h>

int __install_dev_zero (void);
@end example

@subheading Description

This function activates support for the special file @file{/dev/zero}.
When read, @file{dev/zero} always returns @samp{\0} characters.  When
written, @file{/dev/zero} discards the data.  Seeks on @file{/dev/zero}
will always succeed.

The DJGPP debug support functions will interfere with @file{/dev/zero}
(@pxref{File System Extensions}).

@subheading Return Value

On success, a non-zero value is returned; on failure, zero is returned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node int386, int386x, __install_dev_zero, Alphabetical List
@unnumberedsec int386
@c From file ./dos/dos/bdos.txh
@findex int386
@subheading Syntax

@example
#include <dos.h>

int int386(int ivec, union REGS *in, union REGS *out);
@end example

@subheading Description

This function is equal to @code{int86} function.
See @ref{int86}, for further description.

@subheading Return Value

The returned value of @code{EAX}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node int386x, int86, int386, Alphabetical List
@unnumberedsec int386x
@c From file ./dos/dos/bdos.txh
@findex int386x
@subheading Syntax

@example
#include <dos.h>

int int386x(int ivec, union REGS *in, union REGS *out,
            struct SREGS *seg);
@end example

@subheading Description

This function is equal to @code{int86x}.
See @ref{int86}, for further description.

@subheading Return Value

The value of @code{EAX} is returned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node int86, int86x, int386x, Alphabetical List
@unnumberedsec int86
@c From file ./dos/dos/bdos.txh
@findex int86
@tindex DWORDREGS@r{ structure}
@tindex DWORDREGS_W@r{ structure}
@tindex WORDREGS@r{ structure}
@tindex BYTEREGS@r{ structure}
@tindex REGS@r{ union}
@subheading Syntax

@example
#include <dos.h>

int int86(int ivec, union REGS *in, union REGS *out);
@end example

@subheading Description

The @code{union REGS} is defined by @code{<dos.h>} as follows:

@example
struct DWORDREGS @{
  unsigned long edi;
  unsigned long esi;
  unsigned long ebp;
  unsigned long cflag;
  unsigned long ebx;
  unsigned long edx;
  unsigned long ecx;
  unsigned long eax;
  unsigned short eflags;
@};

struct DWORDREGS_W @{
  unsigned long di;
  unsigned long si;
  unsigned long bp;
  unsigned long cflag;
  unsigned long bx;
  unsigned long dx;
  unsigned long cx;
  unsigned long ax;
  unsigned short flags;
@};

struct WORDREGS @{
  unsigned short di, _upper_di;
  unsigned short si, _upper_si;
  unsigned short bp, _upper_bp;
  unsigned short cflag, _upper_cflag;
  unsigned short bx, _upper_bx;
  unsigned short dx, _upper_dx;
  unsigned short cx, _upper_cx;
  unsigned short ax, _upper_ax;
  unsigned short flags;
@};

struct BYTEREGS @{
  unsigned short di, _upper_di;
  unsigned short si, _upper_si;
  unsigned short bp, _upper_bp;
  unsigned long cflag;
  unsigned char bl;
  unsigned char bh;
  unsigned short _upper_bx;
  unsigned char dl;
  unsigned char dh;
  unsigned short _upper_dx;
  unsigned char cl;
  unsigned char ch;
  unsigned short _upper_cx;
  unsigned char al;
  unsigned char ah;
  unsigned short _upper_ax;
  unsigned short flags;
@};

union REGS @{
  struct DWORDREGS d;
#ifdef _NAIVE_DOS_REGS
  struct WORDREGS x;
#else
#ifdef _BORLAND_DOS_REGS
  struct DWORDREGS x;
#else
  struct DWORDREGS_W x;
#endif
#endif
  struct WORDREGS w;
  struct BYTEREGS h;
@};
@end example

Note: The @code{.x.} branch is a problem generator.  Most programs expect
the @code{.x.} branch to have e.g. "@code{.x.ax}" members, and that
they are 16-bit.  If you know you want 32-bit values, use the
@code{.d.eax} members.  If you know you want 16-bit values, use the
@code{.w.ax} members.  The @code{.x.} members behave according to
@code{#defines}, as follows:

@table @code

@item default

If you specify no @code{#define}, the @code{.x.} branch has
"@code{ax}" members and is 32-bit.  This is compatible with previous
versions of djgpp.

@item _NAIVE_DOS_REGS

This define gives you @code{.x.ax}, but they are 16-bit.  This is
probably what most programs ported from 16-bit dos compilers will
want.

@item _BORLAND_DOS_REGS

This define gives you @code{.x.eax} which are 32-bit.  This is
compatible with Borland's 32-bit compilers.

@end table

This function simulates a software interrupt.  Note that, unlike the
@code{__dpmi_int} function, requests that go through @code{int86}
and similar functions are specially processed to make them suitable for
invoking real-mode interrupts from protected-mode programs.  For example,
if a particular routine takes a pointer in @code{BX}, @code{int86} expects
you to put a (protected-mode) pointer in @code{EBX}.  Therefore,
@code{int86} should have specific support for every interrupt and function
you invoke this way.  Currently, it supports only a subset of all
available interrupts and functions:

1) All functions of any interrupt which expects only scalar arguments
registers (i.e., no pointers to buffers).

2) In addition, the following functions of interrupt 21h are supported:
9, 39h, 3Ah, 3Bh, 3Ch, 3Dh, 3Fh, 40h, 41h, 43h, 47h, 56h.

When the interrupt is invoked, the CPU registers are copied from
@var{in}.  After the interrupt, the CPU registers are copied to
@var{out}.

This function is just like @code{int86x} (@pxref{int86x}) except that
suitable default values are used for the segment registers.

See also @ref{int86x}, @ref{intdos}, and @ref{bdos}.

@subheading Return Value

The returned value of @code{EAX}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
union REGS r;
r.x.ax = 0x0100;
r.h.dl = 'c';
int86(0x21, &r, &r);
@end example

@c -----------------------------------------------------------------------------
@node int86x, intdos, int86, Alphabetical List
@unnumberedsec int86x
@c From file ./dos/dos/bdos.txh
@findex int86x
@tindex SREGS@r{ structure}
@subheading Syntax

@example
#include <dos.h>

int int86x(int ivec, union REGS *in, union REGS *out,
           struct SREGS *seg);
@end example

@subheading Description

The @code{struct SREGS} is defined by @code{<dos.h>} as follows:

@example
struct SREGS @{
  unsigned short es;
  unsigned short ds;
  unsigned short fs;
  unsigned short gs;
  unsigned short cs;
  unsigned short ss;
@};
@end example

This function is just like @code{int86} (@pxref{int86}) except that
values you pass in @var{seg} are used for the segment registers instead
of the defaults.

See also @ref{int86}, @ref{intdos}, and @ref{bdos}.

@subheading Return Value

The value of @code{EAX} is returned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
union REGS r;
struct SREGS s;
r.h.ah = 0x31;
r.h.dl = 'c';
r.x.si = si_val;
s.ds = ds_val;
int86x(0x21, &r, &r, &s);
@end example

@c -----------------------------------------------------------------------------
@node intdos, intdosx, int86x, Alphabetical List
@unnumberedsec intdos
@c From file ./dos/dos/bdos.txh
@findex intdos
@subheading Syntax

@example
#include <dos.h>

int intdos(union REGS *in, union REGS *out);
@end example

@subheading Description

This function is just like @code{int86} (@pxref{int86x}) except that
the interrupt vector is 0x21.

@subheading Return Value

@code{EAX}

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node intdosx, intensevideo, intdos, Alphabetical List
@unnumberedsec intdosx
@c From file ./dos/dos/bdos.txh
@findex intdosx
@subheading Syntax

@example
#include <dos.h>

int intdosx(union REGS *in, union REGS *out, struct SREGS *s);
@end example

@subheading Description

This function is just like @code{int86x} (@pxref{int86x}) except that the
interrupt vector is 0x21.

@subheading Return Value

@code{EAX}


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node intensevideo, __internal_readlink, intdosx, Alphabetical List
@unnumberedsec intensevideo
@c From file ./pc_hw/co80/conio.txh
@findex intensevideo

@subheading Syntax

@example
#include <conio.h>

void intensevideo(void);
@end example

@subheading Description

Bit 7 (@samp{MSB}) of the character attribute byte has two possible
effects on EGA and VGA displays: it can either make the character blink
or change the background color to bright (thus allowing for 16
background colors as opposed to the usual 8).  This function sets that
bit to display bright background colors.  After a call to this function,
every character written to the screen with bit 7 of the attribute byte
set, will have a bright background color.  The companion function
@code{blinkvideo} (@pxref{blinkvideo}) has the opposite effect.

Note that there is no BIOS function to get the current status of this
bit, but bit 5 of the byte at @code{0040h:0065h} in the BIOS area
indicates the current state: if it's 1 (the default), blinking
characters will be displayed.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __internal_readlink, _invent_inode, intensevideo, Alphabetical List
@unnumberedsec __internal_readlink
@c From file ./compat/unistd/_irdlink.txh
@findex __internal_readlink
@subheading Syntax

@example
#include <libc/symlink.h>

int __internal_readlink(const char * path, int fhandle,
                        char * buf, size_t max)
@end example

@subheading Description
In general applications shouldn't call this function; use @code{readlink} 
instead (@pxref{readlink}).  However, there is one exception: if you have
a @code{FSEXT} @code{fstat} file handler, and do not want do anything special
about symlinks.  In this case you should call this function from your handler
to set properly @code{S_IFLNK} bit in @code{st_mode}.  This function operates
on either @var{path} @strong{or} @var{fhandle}. In any case, the other arg
should be set to @code{NULL} or 0.

@subheading Return Value

Number of copied characters; value -1 is returned in case of
error and @code{errno} is set.  When value returned is equal to 
@var{size}, you cannot determine if there was enough room to 
copy whole name.  So increase @var{size} and try again.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char buf[FILENAME_MAX + 1];
if (__internal_readlink(0, "/dev/env/DJDIR/bin/sh.exe",
                        buf, FILENAME_MAX) == -1)
   if (errno == EINVAL)
      puts("/dev/env/DJDIR/bin/sh.exe is not a symbolic link.");
@end example

@c -----------------------------------------------------------------------------
@node _invent_inode, ioctl (DOS), __internal_readlink, Alphabetical List
@unnumberedsec _invent_inode
@c From file ./posix/sys/stat/xstat.txh
@findex _invent_inode
@subheading Syntax
@example
ino_t
_invent_inode(const char *name, unsigned time_stamp,
              unsigned long fsize)
@end example

@subheading Description
This invents an inode number for those files which don't have valid DOS
cluster number.  These could be:
@itemize @bullet
@item
 devices like @file{/dev/null} or file system extensions
 (@pxref{File System Extensions})

@item
 empty files which were not allocated disk space yet

@item
 or files on networked drives, for which the redirector doesn't bring the
 cluster number.
@end itemize

To ensure proper operation of this function, you must call it with a filename
in some canonical form.  E.g., with a name returned by @code{truename()}
(@pxref{_truename}), or that returned by @code{_fixpath()} (@pxref{_fixpath}).
The point here is that the entire program @emph{must} abide by these
conventions through its operation, or else you risk getting different inode
numbers for the same file.

@subheading Return Value
0 on error, otherwise the invented inode number for the file.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node ioctl (DOS), ioctl (General description), _invent_inode, Alphabetical List
@unnumberedsec ioctl (DOS)
@c From file ./compat/ioctl/ioctl.txh
@findex ioctl@r{, DOS}
The DOSish version of @code{ioctl} performs an
interrupt 0x21, function 0x44. It takes care of supplying transfer buffers in
low address regions, if they are needed. For an exhaustive description of the
various commands and subcommands, see Ralf Brown's interrupt list.

It is highly recommended to use only the DOS_*
functions listed in @file{sys/ioctl.h}.

@subheading Syntax

@example
#include <sys/ioctl.h>

int ioctl(int fd, int cmd, ... );
@end example


@subheading Description
The parameter @code{fd} must refer to a file descriptor for character device
functions, or the number of a block device (usually current=0, A:=1, ...).

The following constants can be used for the @code{cmd} parameter:
@table @code
@item DOS_GETDEVDATA
Get device information. Returns the device information word from @code{DX}.
The call to @code{ioctl} should look like this:

@example
 int ret_val = ioctl (fd, DOS_GETDEVDATA);
@end example

For another way of achieving the same effect, see @code{_get_dev_info}
(@pxref{_get_dev_info}).

@item DOS_SETDEVDATA
Set device information. Returns the new device information word form @code{DX}
or -1.  The call to @code{ioctl} should look like this:

@example
 int ret_val = ioctl (fd, DOS_SETDEVDATA, 0, dev_info);
@end example

@item DOS_RCVDATA
Read from character device control channel. After @code{cmd} must follow the
number of requested bytes to read and a pointer to a buffer. Returns the number
of bytes actually read or -1 on error.  The call to @code{ioctl} should
look like this:

@example
 unsigned char buf[bytes_to_read];
 int ret_val = ioctl (fd, DOS_RCVDATA, bytes_to_read, &buf);
@end example

@item DOS_SNDDATA
Write to character device control channel. After @code{cmd} must follow the
number of bytes to write and a pointer to a buffer holding the data.
Returns the number of bytes actually written.  An example of a call:

@example
 unsigned char buf[bytes_to_write];
 int ret_val = ioctl (fd, DOS_SNDDATA, bytes_to_write, &buf);
@end example

@item DOS_RCVCTLDATA
Read from block device control channel. See @code{DOS_RCVDATA}.

@item DOS_SNDCTLDATA
Write to block device control channel. See @code{DOS_SNDDATA}.

@item DOS_CHKINSTAT
Check the input status of a file. Returns 0 if not ready of at EOF, @code{0xff}
if file is ready.  Here's an example of how to call:

@example
 int ret_val = ioctl (fd, DOS_CHKINSTAT);
@end example

A more portable way of doing this is by calling @code{select}.
@xref{select}.

@item DOS_CHKOUTSTAT
Check the output status of a file. Returns 0 if not ready of at EOF,
@code{0xff} if file is ready.  @code{select} (@pxref{select}) is
another, more portable way of doing the same.

@item DOS_ISCHANGEABLE
Check if a block device is changeable. Returns 0 for removable or 1 for fixed.
An example of a call:

@example
 int ret_val = ioctl (fd, DOS_ISCHANGEABLE);
@end example


@item DOS_ISREDIRBLK
Check if a block device is remote o local.  The function
@code{_is_remote_drive} (@pxref{_is_remote_drive}) is another way of
returning the same info.

@item DOS_ISREDIRHND
Check if a file handle refers to a local or remote device.  See
@code{_is_remote_handle} (@pxref{_is_remote_handle}) for another way
of doing this.

@item DOS_SETRETRY
Set the sharing retry count. The first extra parameter specifies the pause
between retries, the second number of retries.  An example:

@example
 int ret_val = ioctl (fd, DOS_SETRETRY, pause_between_retries,
                      max_retries);
@end example

@item DOS_GENCHARREQ
Generic character device request.  Example:

@example
 int ret_val = ioctl (fd, DOS_GENCHARREQ, category_and_function,
                      &param_block, si_value, di_value,
                      param_block_size);
@end example

Refer to Ralf Brown's Interrupt List for the details about each function
and relevant parameter block layout.

@item DOS_GENBLKREQ
Generic block device request.  Example of the call:

@example
 int ret_val = ioctl (drive_no, DOS_GENBLKREQ, category_and_function,
                      &param_block, si_value, di_value,
                      param_block_size);
@end example

Note that instead of the handle, the first argument is the disk drive
number (0 = default, 1 = A:, etc.).

@item DOS_GLDRVMAP
Get logical drive map.  A call like the following:

@example
 int ret_val = ioctl (drive_no, DOS_GLDRVMAP);
@end example

@noindent
will return 0 if the block device has only one logical drive assigned,
or a number in the range 1..26 which is the last drive number used to
reference that drive (1 = A:, etc.).  Thus, on a machine which has a
single floppy drive, calling @code{ioctl (1, DOS_GLDRVMAP);} will return
2 if the floppy was last referred to as B:.  This function and the next
one can be used together to prevent DOS from popping the ugly prompt
saying "Insert diskette for drive B: and press any key when ready".

@item DOS_SLDRVMAP
Set logical drive map.  For example, a call like this:

@example
 ioctl (1, DOS_SLDRVMAP);
@end example

@noindent
will cause drive A: to be mapped to drive B:.

@item DOS_QGIOCTLCAPH
Query generic ioctl capability (handle). Test if a handle supports ioctl
functions beyond those in the standard DOS 3.2 set.  Call like this:

@example
 int ret_val = ioctl (fd, DOS_QGIOCTLCAPH, category_and_function);
@end example

This will return zero if the specified IOCTL function is supported, 1 if
not.

@item DOS_QGIOCTLCAPD
Query generic ioctl capability (drive). Test if a drive supports ioctl
functions beyond those in the standard DOS 3.2 set.  Used same as
DOS_QGIOCTLCAPH, but the first argument is a drive number (0 = default,
1 = A:, etc.), not a handle.
@end table

If your specific device driver requires different commands, they must be or'ed
together with the flags listed in @code{<sys/ioctl.h>} to tell the drive about
transfer buffers and what to return.

@subheading Return Value
See description above.

@subheading Device information word
The bits of the device information word have the following meaning:

Character device:
@table @asis
@item 14
Device driver can process IOCTL request

@item 13
output until busy supported

@item 11
driver supports OPEN/CLOSE calls

@item 7
set (indicates device)

@item 6
EOF on input

@item 5
raw (binary) mode

@item 4
device is special (uses INT 29)

@item 3
clock device

@item 2
NUL device

@item 1
standard output

@item 0
standard input

@end table

Disk file:
@table @asis
@item 15
file is remote (DOS 3.0+)

@item 14
don't set file date/time on closing (DOS 3.0+)

@item 11
media not removable

@item 8
(DOS 4 only) generate INT 24 if no disk space on write or read past end of file

@item 7
clear (indicates file)

@item 6
file has not been written

@item 5-0
drive number (0 = A:)

@end table

@subheading Example

@example
#include <sys/ioctl.h>
int main(int argc, char **argv)
@{
   char buf[6];
   short *s;

   open(fd,"EMMQXXX0",O_RDONLY);
   mybuf[0] = '\0';
   s = mybuf;
   ioctl(fd,DOS_SNDDATA,6, (int) &mybuf);
   if(*s ==0x25 )printf("EMM386 >= 4.45\n");
   mybuf[0]='\x02';
   ioctl(fd,DOS_SNDDATA,2,(int )&mybuf);
   printf("EMM Version %d.%d\n",(int )mybuf[0],(int) mybuf[1]);
   close(fd);
@}
@end example

@c -----------------------------------------------------------------------------
@node ioctl (General description), ioctl (UNIX), ioctl (DOS), Alphabetical List
@unnumberedsec ioctl (General description)
@c From file ./compat/ioctl/ioctl.txh
@findex ioctl@r{, General description}
@code{ioctl} performs low level calls to communicate with device drivers. As
there are lots of different device drivers, no really general description is
possible.

The DJGPP version tries to cope with two different flavors of @code{ioctl},
a DOSish and a UNIXish way. To distinguish between DOS-like and UNIX-like
calls, all valid DOS commands have all 3 MSB set to 0, the UNIX command have
at least one of the 3 MSB set to 1.


@c -----------------------------------------------------------------------------
@node ioctl (UNIX), _is_cdrom_drive, ioctl (General description), Alphabetical List
@unnumberedsec ioctl (UNIX)
@c From file ./compat/ioctl/ioctl.txh
@findex ioctl@r{, UNIX}
@tindex winsize@r{ structure}
@subheading Syntax

@example
#include <sys/ioctl.h>

int ioctl(int fd, int cmd, ... );
@end example

@subheading Description
The UNIX version first checks if an FSEXT handler is associated with the file
descriptor @var{fd}. If so, it calls the handler in the usual way
(@pxref{File System Extensions}).

Otherwise,the operation specified by @var{cmd} is performed on the file open
on handle @var{fd}.  The following operations are defined
by the header @file{sys/ioctl.h}:

@table @code
@item TIOCGWINSZ
Fill in the @code{winsize} structure pointed to by the third argument
with the screen width and height.

The @code{winsize} structure is defined in @file{sys/ioctl.h}
as follows:

@example
struct winsize
@{
  unsigned short ws_row;	/* rows, in characters */
  unsigned short ws_col;	/* columns, in characters */
  unsigned short ws_xpixel;	/* horizontal size, pixels */
  unsigned short ws_ypixel;	/* vertical size, pixels */
@};
@end example

@end table

@subheading Return Value
Zero for @code{TIOCGWINSZ}. Otherwise, -1 is returned and @code{errno} is set
to @code{ENOSYS} for all others.

@subheading Example

@example
#include <sys/ioctl.h>
#include <stdio.h>
int main(int argc, char **argv)
@{
  struct winsize sz;

  ioctl(0, TIOCGWINSZ, &screen_size);
  printf("Screen width: %i  Screen height: %i\n", sz.ws_col, sz.ws_row);
  return 0;
@}
@end example
@c -----------------------------------------------------------------------------
@node _is_cdrom_drive, _is_DOS83, ioctl (UNIX), Alphabetical List
@unnumberedsec _is_cdrom_drive
@c From file ./dos/dos/iscdrom.txh
@findex _is_cdrom_drive
@subheading Syntax

@example
#include <dos.h>

int _is_cdrom_drive( const int drive );
@end example

@subheading Description

This function checks if drive number @var{drive} (1 == A:, 2 == B:,
etc.) is a CD-ROM drive.  It works with MSCDEX 2.x and Windows 9X
built-in CDFS support.  

@subheading Return Value

1 if the drive is a CDROM drive, otherwise 0.  

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

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

int main(void)
@{

  if( _is_cdrom_drive( 'R' - 'A' + 1 ) )
  @{
    printf("C: is a CDROM drive.\n");
  @}
  else
  @{
    printf("C: is not a CDROM drive.\n");
  @}

  exit(0);
@}

@end example
@c -----------------------------------------------------------------------------
@node _is_DOS83, _is_executable, _is_cdrom_drive, Alphabetical List
@unnumberedsec _is_DOS83
@c From file ./dos/lfn/_use_lfn.txh
@findex _is_DOS83
@subheading Syntax
 
@example
#include <fcntl.h>

int _is_DOS83 (const char *fname);
@end example

@subheading Description

This function checks the filename pointed to by @var{fname} to 
determine if it is a standard short (8+3) form file name.  The 
filename should only include the name part of the file.  It is
expected the filename will contain a valid long or short file
name (no validation is done to exclude path characters or 
characters always illegal in any file name).  Note: If the filename
contains lower case characters the name is considered to be a
long name and not a standard short name (and the function will
return 0).

The function will return 0 (failure) if there are more than 8 
characters before a period, more than 3 characters after a period, 
more than one period, starts with a period, any lower case characters, 
or any of the special characters @samp{+} @samp{,} @samp{;} @samp{=} @samp{[} @samp{]}, or a space.  The 
special names @file{.} and @file{..} are exceptions and will return success.

This function could be called to determine if a filename is valid on 
DOS before long file name support.  If this function returns 1 the 
filename probably does not have a long name entry on a FAT file 
system.  The library internally calls this function to determine
if a file should have its name lower cased when @pxref{_preserve_fncase} is
false.

@subheading Return value

The function returns an integer 0 (not DOS 8.3) or 1 (DOS 8.3)

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable

@c -----------------------------------------------------------------------------
@node _is_executable, _is_fat32, _is_DOS83, Alphabetical List
@unnumberedsec _is_executable
@c From file ./posix/sys/stat/is_exec.txh
@findex _is_executable
@subheading Syntax

@example
#include <sys/stat.h>

int _is_executable(const char *path, int fhandle,
                   const char *extension);
@end example

@subheading Description

This function determines if a file is executable under DOS/DJGPP
environment.  The file may be given either by its @var{path} or its file
handle @var{fhandle}.  If @var{extension} is non-NULL and non-empty, it
is used first to look up in a list of known extensions which determine
whether the file is executable.  (If the @code{_STAT_EXEC_EXT} bit of
the @code{_djstat_flags} global variable (@pxref{_djstat_flags}) is not
set, this step is skipped.)  If @var{extension} is unavailable or not
enough to determine the result, the first 2 bytes of the file are
checked to contain one of the known @cite{magic numbers} identifying the
file as executable.  If the file's 2 first bytes need to be read but the
read fails, 0 is returned and errno is set.  (The file is only searched
for magic number if the @code{_STAT_EXEC_MAGIC} bit of the
@code{_djstat_flags} variable is set.)

Note that if @code{_STAT_EXEC_MAGIC} is set, but @code{_STAT_EXEC_EXT}
is not, some files which shouldn't be flagged as executables (e.g., COFF
@file{*.o} object files) will have their execute bit set, because they
have the magic number signature at their beginning.  Therefore, only use
the above combination if you want to debug the list of extensions
provided in @file{is_exec.c} file from the library sources.

If the file passed by its handle was open as write-only, and the extension
alone isn't enough to determine whether the file is executable, then this
function returns 0, because it cannot look at the @cite{magic number}.

This function is used internally by @code{f?stat}; you are not supposed
to call it directly.  However, if you call it, and pass file through 
@var{path}, it's up to you to resolve symlinks there.

@subheading Return Value

1 for executable file, 0 otherwise (including in case of errors in
accessing the file).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _is_fat32, _is_ram_drive, _is_executable, Alphabetical List
@unnumberedsec _is_fat32
@c From file ./dos/dos/isfat32.txh
@findex _is_fat32
@subheading Syntax

@example
#include <dos.h>

int _is_fat32( const int drive );
@end example

@subheading Description

This function checks if drive number @var{drive} (1 == A:, 2 == B:,
etc.) is formatted with FAT32.  

For performance reasons the result is cached, hence if a drive is
reformatted either from or to FAT32 a DJGPP program must be restarted.  

@subheading Return Value

1 if the drive is formatted with FAT32, otherwise 0.  

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

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

int main(void)
@{

  if( _is_fat32( 'C' - 'A' + 1 ) )
  @{
    printf("C: is a FAT32 drive.\n");
  @}
  else
  @{
    printf("C: is not a FAT32 drive.\n");
  @}

  exit(0);
@}

@end example
@c -----------------------------------------------------------------------------
@node _is_ram_drive, _is_remote_drive, _is_fat32, Alphabetical List
@unnumberedsec _is_ram_drive
@c From file ./dos/dos/isramdri.txh
@findex _is_ram_drive
@subheading Syntax

@example
#include <dos.h>

int _is_ram_drive( const int drive );
@end example

@subheading Description

This function checks if drive number @var{drive} (1 == A:, 2 == B:,
etc.) is a RAM disk.  It is done by checking if the number of FAT
copies (in the Device Parameter Block) is 1, which is typical of 
RAM disks.  This doesn't @emph{have} to be so, but if it's good
enough for Andrew Schulman et al (@cite{Undocumented DOS, 2nd
edition}), we can use this as well.  

@subheading Return Value

1 if the drive is a RAM drive, otherwise 0.  

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

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

  int i = 4;

  printf("%c: is a RAM drive: %d.\n",  'A' - 1 + i, _is_ram_drive( i ) )

@end example
@c -----------------------------------------------------------------------------
@node _is_remote_drive, _is_remote_handle, _is_ram_drive, Alphabetical List
@unnumberedsec _is_remote_drive
@c From file ./dos/dos/remotdrv.txh
@findex _is_remote_drive
@subheading Syntax

@example
int _is_remote_drive(int drv);
@end example

@subheading Description

Given the drive number in @var{drv} (A: = 0, B: = 1, etc.), this
function returns non-zero if the drive is treated by DOS as a remote
(networked) drive, or zero otherwise.  It does so by calling subfunction
09h of the DOS IOCTL function (interrupt 21h, AX=4409h) and looking at
bit 12 of the device attribute word returned in the DX register.

Note that DOS treats CD-ROM drives as remote.

@subheading Return Value

Zero for local drives, non-zero for remote and CD-ROM drives.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable



@c -----------------------------------------------------------------------------
@node _is_remote_handle, isalnum, _is_remote_drive, Alphabetical List
@unnumberedsec _is_remote_handle
@c From file ./dos/dos/remotdrv.txh
@findex _is_remote_handle
@subheading Syntax

@example
int _is_remote_handle(int fhandle);
@end example

@subheading Description

Given the file handle of an open file in @var{fhandle}, this function
returns non-zero if the drive where that file resides is treated by DOS
as a remote (networked) drive, or zero otherwise.  It does so by calling
subfunction 0Ah of the DOS IOCTL function (interrupt 21h, AX=440Ah) and
looking at bit 15 of the device attribute word returned in the DX
register.

Note that DOS treats CD-ROM drives as remote.

@subheading Return Value

Zero for files on local drives, non-zero for files on remote and CD-ROM
drives.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node isalnum, isalpha, _is_remote_handle, Alphabetical List
@unnumberedsec isalnum
@c From file ./ansi/ctype/isalnum.txh
@findex isalnum
@subheading Syntax

@example
#include <ctype.h>

int isalnum(int c);
@end example

@subheading Description

Tells if @var{c} is any letter or digit.

@subheading Return Value

Nonzero if @var{c} is a letter or digit, else zero.



@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node isalpha, isascii, isalnum, Alphabetical List
@unnumberedsec isalpha
@c From file ./ansi/ctype/isalpha.txh
@findex isalpha
@subheading Syntax

@example
#include <ctype.h>

int isalpha(int c);
@end example

@subheading Description

Tells if @var{c} is a letter.

@subheading Return Value

Nonzero if @var{c} is a letter, else zero.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node isascii, isatty, isalpha, Alphabetical List
@unnumberedsec isascii
@c From file ./ansi/ctype/isascii.txh
@findex isascii
@subheading Syntax

@example
#include <ctype.h>

int isascii(int c);
@end example

@subheading Description

Tells if @var{c} is an ASCII character (0x00 to 0x7f).

@subheading Return Value

Nonzero if @var{c} is ASCII, else zero.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node isatty, isblank, isascii, Alphabetical List
@unnumberedsec isatty
@c From file ./posix/unistd/isatty.txh
@findex isatty
@subheading Syntax

@example
#include <unistd.h>

int isatty(int fd);
@end example

@subheading Description

Tells if the file descriptor refers to a terminal device or not.

@subheading Return Value

Nonzero if @var{fd} is a terminal device, zero  otherwise.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
if (isatty(1))
  fflush(stdout);
@end example

@c -----------------------------------------------------------------------------
@node isblank, iscntrl, isatty, Alphabetical List
@unnumberedsec isblank
@c From file ./ansi/ctype/isblank.txh
@findex isblank
@subheading Syntax

@example
#include <ctype.h>

int isblank(int c);
@end example

@subheading Description

Tells if @var{c} is a blank character.  A blank character is used
to separate words, e.g.: @samp{ } or @samp{\t}.

@subheading Return Value

Nonzero if @var{c} is a blank character, else zero.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node iscntrl, isdigit, isblank, Alphabetical List
@unnumberedsec iscntrl
@c From file ./ansi/ctype/iscntrl.txh
@findex iscntrl
@subheading Syntax

@example
#include <ctype.h>

int iscntrl(int c);
@end example

@subheading Description

Tells if @var{c} is a control character.

@subheading Return Value

Nonzero if @var{c} is a control character, else zero.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node isdigit, isfinite, iscntrl, Alphabetical List
@unnumberedsec isdigit
@c From file ./ansi/ctype/isdigit.txh
@findex isdigit
@subheading Syntax

@example
#include <ctype.h>

int isdigit(int c);
@end example

@subheading Description

Tells if @var{c} is a digit.

@subheading Return Value

Nonzero if @var{c} is a digit, else zero.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node isfinite, isgraph, isdigit, Alphabetical List
@unnumberedsec isfinite
@c From file ./c99/math/ismacros.txh
@findex isfinite
@subheading Syntax

@example
#include <math.h>

int isfinite(x);
@end example

@subheading Description

The macro @code{isfinite} will determine whether its argument @var{x} has a finite
value (zero, subnormal, or normal, and not infinite or NaN).  The operands can be
of any real floating-point type.

@subheading Return Value

non-zero for a finite value;
zero else.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@end multitable


@subheading Example

@example
long double ld = 3.14159265358979;

if (isfinite(ld))
  printf("value is finite.\n");
else if (isinf(ld))
  printf("value is infinite.\n");
else if (isnan(ld))
  printf("value is NaN.\n");

@end example

@c -----------------------------------------------------------------------------
@node isgraph, isgreater, isfinite, Alphabetical List
@unnumberedsec isgraph
@c From file ./ansi/ctype/isgraph.txh
@findex isgraph
@subheading Syntax

@example
#include <ctype.h>

int isgraph(int c);
@end example

@subheading Description

Tells if @var{c} is a visible printing character.  Space is not
included. 

@subheading Return Value

Nonzero if @var{c} is a visible printing character, else zero.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node isgreater, isgreaterequal, isgraph, Alphabetical List
@unnumberedsec isgreater
@c From file ./c99/math/ismacros.txh
@findex isgreater
@subheading Syntax

@example
#include <math.h>

int isgreater(x, y);
@end example

@subheading Description

The macro @code{isgreater} will determine whether its first argument @var{x} is
greater than its second argument @var{y} without failing if one of the operands is
@code{NaN}.  The operands can be of any real floating-point type and the macro is
guaranteed to evaluate their operands only once.

@subheading Return Value

zero if one of @var{x} or @var{y} is @code{NaN};
else the result of (@var{x}) > (@var{y}).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@end multitable


@subheading Example

@example
float f = 1;
double d = INFINITY;

if (isnan(f) || isnan(d))
  printf("f or d is NaN.\n");
else
@{
  if (isgreater(f, d))
    printf("f is greater than d.\n");
  else
    printf("f is not greater than d.\n");
@}

@end example

@c -----------------------------------------------------------------------------
@node isgreaterequal, isinf, isgreater, Alphabetical List
@unnumberedsec isgreaterequal
@c From file ./c99/math/ismacros.txh
@findex isgreaterequal
@subheading Syntax

@example
#include <math.h>

int isgreaterequal(x, y);
@end example

@subheading Description

The macro @code{isgreaterequal} will determine whether its first argument @var{x} is
greater than or equal to its second argument @var{y} without failing if one of the operands
is @code{NaN}.  The operands can be of any real floating-point type and the macro is
guaranteed to evaluate their operands only once.

@subheading Return Value

zero if one of @var{x} or @var{y} is @code{NaN};
else the result of (@var{x}) >= (@var{y}).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@end multitable


@subheading Example

@example
float f = 1;
double d = INFINITY;

if (isnan(f) || isnan(d))
  printf("f or d is NaN.\n");
else
@{
  if (isgreaterequal(f, d))
    printf("f is greater than or equal to d.\n");
  else
    printf("f is not greater than d.\n");
@}

@end example

@c -----------------------------------------------------------------------------
@node isinf, isless, isgreaterequal, Alphabetical List
@unnumberedsec isinf
@c From file ./c99/math/ismacros.txh
@findex isinf
@subheading Syntax

@example
#include <math.h>

int isinf(x);
@end example

@subheading Description

The macro @code{isinf} will determine whether its argument @var{x} value is a positive
or negative infinity.  The operands can be of any real floating-point type.

@subheading Return Value

non-zero for a infinite value (positive or negative);
zero else.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@end multitable


@subheading Example

@example
double d = INFINITY;

if (isinf(d))
  printf("value is infinite.\n");
else if (isnan(d))
  printf("value is NaN.\n");
else
  printf("value is finite.\n");

@end example

@c -----------------------------------------------------------------------------
@node isless, islessequal, isinf, Alphabetical List
@unnumberedsec isless
@c From file ./c99/math/ismacros.txh
@findex isless
@subheading Syntax

@example
#include <math.h>

int isless(x, y);
@end example

@subheading Description

The macro @code{isless} will determine whether its first argument @var{x} is less than
its second argument @var{y} without failing if one of the operands is @code{NaN}.  The
operands can be of any real floating-point type and the macro is guaranteed to evaluate
their operands only once.

@subheading Return Value

zero if one of @var{x} or @var{y} is @code{NaN};
else the result of (@var{x}) < (@var{y}).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@end multitable


@subheading Example

@example
float f = 1;
double d = INFINITY;

if (isnan(f) || isnan(d))
  printf("f or d is NaN.\n");
else
@{
  if (isless(f, d))
    printf("f is less than d.\n");
  else
    printf("f is not less than d.\n");
@}

@end example

@c -----------------------------------------------------------------------------
@node islessequal, islessgreater, isless, Alphabetical List
@unnumberedsec islessequal
@c From file ./c99/math/ismacros.txh
@findex islessequal
@subheading Syntax

@example
#include <math.h>

int islessequal(x, y);
@end example

@subheading Description

The macro @code{islessequal} will determine whether its first argument @var{x} is less
than or equal to its second argument @var{y} without failing if one of the operands is
@code{NaN}.  The operands can be of any real floating-point type and the macro is
guaranteed to evaluate their operands only once.

@subheading Return Value

zero if one of @var{x} or @var{y} is @code{NaN};
else the result of (@var{x}) <= (@var{y}).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@end multitable


@subheading Example

@example
float f = 1;
double d = INFINITY;

if (isnan(f) || isnan(d))
  printf("f or d is NaN.\n");
else
@{
  if (islessequal(f, d))
    printf("f is less than or equal to d.\n");
  else
    printf("f is not less than d.\n");
@}

@end example

@c -----------------------------------------------------------------------------
@node islessgreater, islower, islessequal, Alphabetical List
@unnumberedsec islessgreater
@c From file ./c99/math/ismacros.txh
@findex islessgreater
@subheading Syntax

@example
#include <math.h>

int islessgreater(x, y);
@end example

@subheading Description

The macro @code{islessgreater} will determine whether its first argument @var{x} is less
than or greater than its second argument @var{y} without failing if one of the operands
is @code{NaN}.  The operands can be of any real floating-point type and the macro is
guaranteed to evaluate their operands only once.

@subheading Return Value

zero if one of @var{x} or @var{y} is @code{NaN};
else the result of (@var{x}) < (@var{y}) || (@var{x}) > (@var{y}).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@end multitable


@subheading Example

@example
double d = 1;
long double ld = 1;

if (isnan(ld) || isnan(d))
  printf("ld or d is NaN.\n");
else
@{
  if (islessgreater(lf, d))
    printf("ld is less than d or ld is greater than d.\n");
  else
    printf("ld is equal to d.\n");
@}

@end example

@c -----------------------------------------------------------------------------
@node islower, isnan, islessgreater, Alphabetical List
@unnumberedsec islower
@c From file ./ansi/ctype/islower.txh
@findex islower
@subheading Syntax

@example
#include <ctype.h>

int islower(int c);
@end example

@subheading Description

Tells if @var{c} is lower case or not.

@subheading Return Value

Nonzero if @var{c} is lower case, else zero.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node isnan, isnormal, islower, Alphabetical List
@unnumberedsec isnan
@c From file ./c99/math/ismacros.txh
@findex isnan
@subheading Syntax

@example
#include <math.h>

int isnan(x);
@end example

@subheading Description

The macro @code{isnan} will determine whether its argument @var{x} is a NaN.  The operands
can be of any real floating-point type.

@subheading Return Value

non-zero for NaN;
zero else.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@end multitable


@subheading Example

@example
float f = NAN;

if (isnan(f))
  printf("value is NaN.\n");
else if (isinf(f))
  printf("value is infinite.\n");
else
  printf("value is finite.\n");

@end example

@c -----------------------------------------------------------------------------
@node isnormal, isprint, isnan, Alphabetical List
@unnumberedsec isnormal
@c From file ./c99/math/ismacros.txh
@findex isnormal
@subheading Syntax

@example
#include <math.h>

int isnormal(x);
@end example

@subheading Description

The macro @code{isnormal} will determine whether its argument @var{x} is normal
(neither zero, subnormal, infinite nor NaN).  The operands can be of any real
floating-point type.

@subheading Return Value

non-zero for a normal value;
zero else.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@end multitable


@subheading Example

@example
long double ld = 3.14159265358979;

if (isfinite(ld))
@{
  if (isnormal(ld))
    printf("value is normal.\n");
  else
    printf("value is either zero or subnormal.\n");
@}
else
  printf("value is either infinity or NaN.\n");

@end example

@c -----------------------------------------------------------------------------
@node isprint, ispunct, isnormal, Alphabetical List
@unnumberedsec isprint
@c From file ./ansi/ctype/isprint.txh
@findex isprint
@subheading Syntax

@example
#include <ctype.h>

int isprint(int c);
@end example

@subheading Description

Tells if @var{c} is a printing character, which includes the space
character.

@subheading Return Value

Nonzero if @var{c} is a printing character, else zero.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node ispunct, isspace, isprint, Alphabetical List
@unnumberedsec ispunct
@c From file ./ansi/ctype/ispunct.txh
@findex ispunct
@subheading Syntax

@example
#include <ctype.h>

int ispunct(int c);
@end example

@subheading Description

Tells if @var{c} is any printing character except space and those
indicated by @code{isalnum}. 

@subheading Return Value

Nonzero if @var{c} is punctuation, else zero.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node isspace, isunordered, ispunct, Alphabetical List
@unnumberedsec isspace
@c From file ./ansi/ctype/isspace.txh
@findex isspace
@subheading Syntax

@example
#include <ctype.h>

int isspace(int c);
@end example

@subheading Description

Tells if @var{c} is whitespace, that is, carriage return, newline, form
feed, tab, vertical tab, or space.

@subheading Return Value

Nonzero if @var{c} is whitespace, else zero.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node isunordered, isupper, isspace, Alphabetical List
@unnumberedsec isunordered
@c From file ./c99/math/ismacros.txh
@findex isunordered
@subheading Syntax

@example
#include <math.h>

int isunordered(x);
@end example

@subheading Description

The macro @code{isunordered} will determine whether its arguments @var{x} or @var{y} are unordered.
The operands can be of any real floating-point type.

@subheading Return Value

non-zero if one of @var{x} or @var{y} is @code{NaN};
zero else.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@end multitable


@subheading Example

@example
float pi = 3.14159;
long double x = NAN;

if (isunordered(pi, x))
  printf("one of the values is NaN.\n");

@end example

@c -----------------------------------------------------------------------------
@node isupper, isxdigit, isunordered, Alphabetical List
@unnumberedsec isupper
@c From file ./ansi/ctype/isupper.txh
@findex isupper
@subheading Syntax

@example
#include <ctype.h>

int isupper(int c);
@end example

@subheading Description

Tells if @var{c} is an upper case character or not.

@subheading Return Value

Nonzero if @var{c} is upper case, else zero.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node isxdigit, itoa, isupper, Alphabetical List
@unnumberedsec isxdigit
@c From file ./ansi/ctype/isxdigit.txh
@findex isxdigit
@subheading Syntax

@example
#include <ctype.h>

int isxdigit(int c);
@end example

@subheading Description

Tells if @var{c} is a valid hexadecimal digit or not.  This includes
@code{[0-9a-fA-F]}. 

@subheading Return Value

Nonzero if @var{c} is a hex digit, else zero.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node itoa, kbhit, isxdigit, Alphabetical List
@unnumberedsec itoa
@c From file ./compat/stdlib/itoa.txh
@findex itoa
@subheading Syntax

@example
#include <stdlib.h>

char * itoa(int value, char *string, int radix)
@end example

@subheading Description

This function converts its argument @var{value} into a null-terminated
character string using @var{radix} as the base of the number system.  The
resulting string with a length of upto 33 bytes (including the optional
sign and the terminating @code{NULL} is put into the buffer whose address
is given by @var{string}.  For radixes other than 10, @var{value} is
treated as an unsigned int (i.e., the sign bit is not interpreted as
such).  The argument @var{radix} should specify the base, between 2 and
36, in which the string representation of @var{value} is requested.

@subheading Return Value
  
A pointer to @var{string}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char binary_str[33];

(void)itoa(num, binary_str, 2);
@end example


@c -----------------------------------------------------------------------------
@node kbhit, kill, itoa, Alphabetical List
@unnumberedsec kbhit
@c From file ./pc_hw/kb/kbhit.txh
@findex kbhit
@subheading Syntax

@example
#include <pc.h>

int kbhit(void);
@end example

@subheading Description

If the user has hit a key, this function will detect it.  This function
is very fast when there is no key waiting, so it may be used inside
loops as needed. 

If you test shift/alt/ctrl status with bios calls (e.g., using
@code{bioskey (2)} or @code{bioskey (0x12)}) then you should also use
bios calls for testing for keys.  This can be done with by
@code{bioskey (1)} or @code{bioskey (0x11)}.  Failing to do so can
cause trouble in multitasking environments like DESQview/X.

@subheading Return Value

Nonzero if a key has been hit, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
while (!kbhit())
  do_stuff();
@end example

@c -----------------------------------------------------------------------------
@node kill, l64a, kbhit, Alphabetical List
@unnumberedsec kill
@c From file ./posix/signal/kill.txh
@findex kill
@subheading Syntax

@example
#include <signal.h>

int	kill(pid_t _pid, int _sig);
@end example

@subheading Description

If @var{_pid} is the current @code{getpid()}, the given @var{_sig} is
raised with @ref{raise}.

@subheading Return Value

-1 on error, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node l64a, labs, kill, Alphabetical List
@unnumberedsec l64a
@c From file ./posix/stdlib/l64a.txh
@findex l64a
@subheading Syntax

@example
#include <stdlib.h>

char *l64a(long value);
@end example

@subheading Description

This function takes a @code{long} argument and returns a pointer to its
radix-64 representation.  Negative values are supported as well.
The resulting string can be turned back into a @code{long} value by the
@code{a64l} function (@pxref{a64l}).

@subheading Return Value

A pointer to a static buffer containing the radix-64 representation of
@var{value}.  Subsequent calls will overwrite the contents of this buffer.
If @var{value} is @code{0L}, this function returns an empty string.

@subheading Radix-64
@cindex radix-64

The radix-64 @sc{ascii} representation is a notation whereby 32-bit integers
are represented by up to 6 @sc{ascii} characters; each character represents
a single radix-64 digit.  Radix-64 refers to the fact that each digit in this
representation can take 64 different values.
If the @code{long} type is more than 32 bits in size, only the low-order
32 bits are used.
The characters used to represent digits are @samp{.} (dot) for 0, @samp{/}
for 1, @samp{0} through @samp{9} for 2 to 11, @samp{A} through @samp{Z} for
12 to 37, and @samp{a} through @samp{z} for 38 to 63.

Note that this is @emph{not} the same encoding used by either uuencode or the
MIME base64 encoding.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
This function is new to the Posix 1003.1-200x draft
@end enumerate
@c -----------------------------------------------------------------------------
@node labs, lchown, l64a, Alphabetical List
@unnumberedsec labs
@c From file ./ansi/stdlib/labs.txh
@findex labs
@subheading Syntax

@example
#include <stdlib.h>

long labs(long x);
@end example

@subheading Description

This function takes the absolute value of @var{x}.  @xref{abs}.

@subheading Return Value

|@var{x}|


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node lchown, ldexp, labs, Alphabetical List
@unnumberedsec lchown
@c From file ./compat/unistd/lchown.txh
@findex lchown
@subheading Syntax

@example
#include <unistd.h>

int lchown(const char *file, int owner, int group);
@end example

@subheading Description

This function does nothing under MS-DOS.

@subheading Return Value

This function always returns zero if the file exists (it does not
follow symbolic links), else it returns -1 and sets @code{errno} 
to @code{ENOENT}.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node ldexp, ldiv, lchown, Alphabetical List
@unnumberedsec ldexp
@c From file ./ansi/math/ldexp.txh
@findex ldexp
@subheading Syntax

@example
#include <math.h>

double ldexp(double val, int exp);
@end example

@subheading Description

This function computes @math{@var{val}*2^@var{exp}}.

@subheading Return Value

@math{@var{val}*2^@var{exp}}.  @code{ldexp(0., exp)} returns 0 for all
values of @code{exp}, without setting @code{errno}.  For non-zero values
of @var{val}, @code{errno} is set to @code{ERANGE} if the result cannot
be accurately represented by a @code{double}, and the return value is
then the nearest representable @code{double} (possibly, an @code{Inf}).
If @var{val} is a @code{NaN} or @code{Inf}, the return value is
@code{NaN} and @code{errno} is set to @code{EDOM}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
ldexp(3.5,4) == 3.5 * (2^4) == 56.0
@end example

@c -----------------------------------------------------------------------------
@node ldiv, lfilelength, ldexp, Alphabetical List
@unnumberedsec ldiv
@c From file ./ansi/stdlib/ldiv.txh
@findex ldiv
@tindex ldiv_t@r{ type}
@subheading Syntax

@example
#include <stdlib.h>

ldiv_t ldiv(long numerator, long denominator);
@end example

@subheading Description

Returns the quotient and remainder of the division @var{numerator}
divided by @var{denominator}.  The return type is as follows:

@example
typedef struct @{
  long quot;
  long rem;
@} ldiv_t;
@end example

@subheading Return Value

The results of the division are returned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
ldiv_t l = ldiv(42, 3);
printf("42 = %ld x 3 + %ld\n", l.quot, l.rem);

ldiv(+40, +3) = @{ +13, +1 @}
ldiv(+40, -3) = @{ -13, +1 @}
ldiv(-40, +3) = @{ -13, -1 @}
ldiv(-40, -3) = @{ +13, -1 @}

@end example

@c -----------------------------------------------------------------------------
@node lfilelength, lfind, ldiv, Alphabetical List
@unnumberedsec lfilelength
@c From file ./posix/sys/stat/lfilelen.txh
@findex lfilelength
@subheading Syntax

@example
#include <io.h>

long long lfilelength(int fhandle);
@end example

@subheading Description

This function returns the size, in bytes, of a file whose handle is
specified in the argument @var{fhandle}.  To get the handle of a file
opened by @code{fopen} (@pxref{fopen}) or @code{freopen} (@pxref{freopen}),
you can use @code{fileno} macro (@pxref{fileno}).

@subheading Return Value

The size of the file in bytes, or (if any error occurred) -1LL and
@code{errno} set to a value describing the cause of the failure.

The return value is of type @code{long long} which allows file sizes of
@math{2^63-1} bytes to be returned.  Note that FAT16 limits files to near
@math{2^31} bytes and FAT32 limits files to @math{2^32-2} bytes.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  printf("Size of file to which STDIN is redirected is %ld\n", 
          lfilelength(0));
@end example

@c -----------------------------------------------------------------------------
@node lfind, _lfn_gen_short_fname, lfilelength, Alphabetical List
@unnumberedsec lfind
@c From file ./posix/search/lfind.txh
@findex lfind
@subheading Syntax

@example
#include <search.h>

void * lfind(const void *key, void *base, size_t *nelp, size_t width, 
             int (*compar)(const void *, const void *));  
@end example

@subheading Description

This function searches the array @var{base} of elements of size
@var{width}, currently containing @var{nelp} elements, for the element
identified by @var{key} using the comparison function @var{compar}.  

The function @var{compar} should return 0 when its inputs are equal
and not 0 otherwise.  

See also @code{lsearch} (@pxref{lsearch}).  

@subheading Return Value

A pointer to the found element or @code{NULL} if not present.  

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
#include <search.h>
#include <stdio.h>
#include <string.h>

#define N_ELEM       50
#define ELEM_SIZE    50
#define COMPARE_FUN  (int (*)(const void *, const void *)) strcmp

char arr[N_ELEM][ELEM_SIZE];
size_t n_arr = 0;

int main(void)
@{
  char *entry;

  entry = lfind("Anyone there?", arr, &n_arr, ELEM_SIZE, COMPARE_FUN);
  if( entry )
  @{
    printf("Someone there: %s!\n", entry);
  @}
  else
  @{
    printf("Noone there...\n");
  @}

  return 0;
@}

@end example

@c -----------------------------------------------------------------------------
@node _lfn_gen_short_fname, _lfn_get_ftime, lfind, Alphabetical List
@unnumberedsec _lfn_gen_short_fname
@c From file ./dos/lfn/_use_lfn.txh
@findex _lfn_gen_short_fname
@subheading Syntax
 
@example
#include <fcntl.h>

char * _lfn_gen_short_fname (const char *long_fname, char *short_fname);
@end example

@subheading Description

This function generates a short (8+3) filename alias for the long
filename pointed to by @var{long_fname} and puts it into the buffer
pointed to by @var{short_fname}.  It uses the same algorithm that
Windows 9x uses, with the exception that the returned short name will
never have a numeric tail, because this function doesn't check the
directory to see whether the generated short name will collide with
any other file in the directory.  Note that @var{long_fname} must
contain only the name part of a file; elements of a full pathname
(like @kbd{:} or @kbd{/} are not allowed (they will cause the
function to fail).  @var{short_fname} will be returned upper-cased,
since that is how 8+3 filenames are stored in directory entries.

When the LFN API is not supported (@pxref{_use_lfn}), the function
simply converts up to 12 characters of @var{long_fname} to upper-case
and returns that.  It will do the same if @var{long_fname} includes any
characters illegal in a filename.

This function returns incorrect results on Windows 2000 and Windows XP
due to bugs in the implementation of the DPMI call on those platforms.
Do not use this function in those environments.

You might need to call this function if you want to know whether a given
filename is valid on MSDOS: if a case-sensitive string comparison
function such as @code{strcmp} (@pxref{strcmp}) returns a 0 when it
compares the original long filename with the short one returned by
@code{_lfn_gen_short_fname}, then the filename is a valid DOS name.
(Note that if @var{long_fname} is in lower case, it might not compare
equal with @var{short_fname} because of the case difference.)

@subheading Return value

The function returns a pointer to @var{short_fname}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
#include <stdio.h>
#include <string.h>
#include <fcntl.h>

int dos_check (char *fname)
@{
  char fshort[13];
  int retval;

  if (stricmp (_lfn_gen_short_fname (fname, fshort), fname) == 0)
  @{
    printf ("%s is a valid MSDOS 8+3 filename\n", fname);
    retval = 1;
  @}
  else
  @{
    printf ("%s will have to be changed for MSDOS\n", fname);
    retval = 0;
  @}
  return retval;
@}
@end example


@c -----------------------------------------------------------------------------
@node _lfn_get_ftime, __libc_termios_exist_queue, _lfn_gen_short_fname, Alphabetical List
@unnumberedsec _lfn_get_ftime
@c From file ./dos/lfn/_use_lfn.txh
@findex _lfn_get_ftime
@subheading Syntax
 
@example
#include <fcntl.h>

char _lfn_get_ftime (int fhandle, int flag);
@end example

@subheading Description

This function returns creation and access time for files that reside on
a filesystem which supports long filenames (such as Windows 95).  Files
which reside on native FAT filesystems will cause this function to fail.
The @var{fhandle} parameter is the file handle as returned by one of the
functions which open or create files.  The @var{flag} parameter
determines which time (creation or access) is returned.  It can be set
to one of the following:

@table @code
@item _LFN_ATIME

Causes @code{_lfn_get_ftime} to return the time when the file was last
accessed.  (Currently, it actually only returns the @emph{date} of last
access; the time bits are all zeroed.)

@item _LFN_CTIME

Causes @code{_lfn_get_ftime} to return the time when the file was
created.  Note that if the file was created by a program which doesn't
support long filenames, this time will be zero.
@end table

@subheading Return value

The file time stamp, as a packed unsigned int value:

@table @code
@item Bits 0-4

seconds divided by 2

@item Bits 5-10

minutes (0-59)

@item Bits 11-15

hours (0-23)

@item Bits 16-20

day of the month (1-31)

@item Bits 21-24

month (1 = January)

@item Bits 25-31

year offset from 1980 (add 1980 to get the actual year)

@end table

If the underlying system calls fail, the function will return 0 and set
@code{errno} to an appropriate value.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
 unsigned file_stamp = _lfn_get_ftime (handle, _LFN_CTIME);
@end example


@c -----------------------------------------------------------------------------
@node __libc_termios_exist_queue, __libc_termios_init, _lfn_get_ftime, Alphabetical List
@unnumberedsec __libc_termios_exist_queue
@c From file ./posix/termios/tminit.txh
@findex __libc_termios_exist_queue
@subheading Syntax

@example
#include <libc/ttyprvt.h>

int __libc_termios_exist_queue (void);
@end example

@subheading Description

This function checks whether there are any characters buffered in the
termios internal queue.  Functions that work on file handles which might
be hooked by termios should call this function before they invoke system
calls which test if there are any characters available for input.

@subheading Return Value

Non-zero if some characters are buffered, zero otherwise.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __libc_termios_init, libm, __libc_termios_exist_queue, Alphabetical List
@unnumberedsec __libc_termios_init
@c From file ./posix/termios/tminit.txh
@findex __libc_termios_init
@subheading Syntax

@example
#include <libc/ttyprvt.h>

void __libc_termios_init (void);
@end example

@subheading Description

This function sets read/write hooks for the termios emulation and import
parameters. Currently importing parameters is not supported, the
emulation is resolved by only internal(static) parameters.  Note that
this function is automatically called by the other termios functions.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node libm, link, __libc_termios_init, Alphabetical List
@unnumberedsec libm
@c From file ./pc_hw/fpu/libm.txh
@subheading Syntax

@example
#include <libm/math.h>

enum fdversion @{fdlibm_ieee = -1, fdlibm_svid, fdlibm_xopen,
                fdlibm_posix@};

#define _LIB_VERSION_TYPE enum fdversion
#define _LIB_VERSION _fdlib_version  

extern  _LIB_VERSION_TYPE  _LIB_VERSION;

#define _IEEE_  fdlibm_ieee
#define _SVID_  fdlibm_svid
#define _XOPEN_ fdlibm_xopen
#define _POSIX_ fdlibm_posix

_LIB_VERSION_TYPE _LIB_VERSION = _IEEE_;
@end example

@subheading Description

The alternate math library, @file{libm.a}, originally written by
@dfn{Cygnus support}, provides versions of mathematical functions which
comply to several different standards of behavior in abnormal cases, and
are sometimes more accurate than those included in the default
@file{libc.a} library, in particular when elaborate argument reduction
is required to avoid precision loss.  Functions in @file{libm.a} allow
to create programs with well-defined and standard-compliant behavior
when numerical errors occur, and provide the application with a means to
control their behavior in abnormal cases via the @code{matherr}
callback.  They almost never rely on the features specific to the x87
FPU, and are thus slower and sometimes slightly less accurate than the
functions from @file{libc.a}.

In contrast, the functions in the default @file{libc.a} library are
written for maximum speed and exploitation of the x87 FPU features, do
not call @code{matherr}, and are therefore much faster and sometimes
more accurate (due to the extended 80-bit precision with which the x87
FPU carries its calculations).

Another aspect of differences between functions in @file{libc.a} and in
@file{libm.a} is the value returned when the result overflows a
@code{double}.  The functions from @file{libc.a} always return a
suitably signed infinity, @code{Inf}, whereas for functions from
@file{libm.a} an application can arrange for a large but finite value to
be returned.  Getting finite return values might be important in certain
kinds of mathematical computations where the special rules defined for
infinities (e.g., @math{Inf + a = Inf}) might be inappropriate.

Refer to @ref{Math, description of the @file{libm.a} functions,
Mathematical Functions, libm, The Cygnus C Math Library}, for detailed
documentation of the individual functions from @file{libm.a}.  This
section explains the general setup of using those functions from DJGPP
programs.

To use the alternate math library with your program, you need to do the
following:

@itemize @bullet

@item
Include the header @code{<libm/math.h>}.  Alternatively, you can include
@code{<math.h>} as usual and compile with @samp{-D_USE_LIBM_MATH_H}
option to @code{gcc}, which will cause it to use @file{libm/math.h}
instead of the default @file{math.h}.  (The second possibility leaves
the source ANSI-compliant.)

@item
Set the global variable @code{_fdlib_version} to a value other than the
default @code{_IEEE_}.  The possible values are listed and explained
below.

@item
At the beginning of your @code{main} function, set the FPU to a
predictable state by calling @code{_clear87} (@pxref{_clear87}) and
@code{_fpreset} (@pxref{_fpreset}) library functions.  (Another
possibility is to make these calls in a function declared with
@code{__attribute__((constructor))}, so it will be called before
@code{main}.)

@item
Link your program with the @file{libm.a} library, e.g. by specifying
@samp{-lm} on the link command line.

@end itemize

The functions in @file{libm.a} can emulate different standards.  You can
select to which standard your program will comply by setting the global
variable @code{_fdlib_version} (or the macro @code{_LIB_VERSION} which
evaluates to it) to one of the values below.  This will only affect the
behavior of the math functions when an error is signaled by the FPU.

@table @code

@item _IEEE_
The default value, specifies IEEE-compliant operation.  In case of an
error, this version will immediately return whatever result is computed
by the FPU, and will @strong{not} set @code{errno}.  If the result
overflows, an @code{Inf} is returned.  This version gives the fastest
code.

@item _POSIX_
In case of an error, this version will set @code{errno} to the
appropriate value (@code{EDOM} or @code{ERANGE}) and return to the
caller, without calling the @code{matherr} function (@pxref{matherr}).
If the result overflows, an @code{Inf} is returned.  This version should
be used for maximum POSIX- and ANSI-compliance.

@item _SVID_
This version is compliant with the @dfn{System V Interface Definition}.
This is the slowest version.  In case of an error, it calls the
@code{matherr} function (@pxref{matherr}), which can be customized to
the specific application needs.  If @code{matherr} returns zero, a
message is printed to the standard error stream which states the name of
the function that generated the error and the error type, and
@code{errno} is set.  If @code{matherr} returns non-zero, there will be
no message and @code{errno} will be left unaltered.  If the result
overflows, this version returns @code{HUGE}, a large but finite value
defined by @file{libm/math.h}.

@item _XOPEN_
Complies to the X/Open specifications.  It behaves exactly like
@code{_SVID_}, but it never prints an error message, even if
@code{matherr} returns zero, and @code{Inf} us returned when a result
overflows.

@end table

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example

/*  Testing errno == EDOM after sqrt(-1).

    !!!  MUST compile with -lm  !!!  */

#include <assert.h>
#include <errno.h>
#include <stdio.h>
#include <libm/math.h> /* or #define _USE_LIBM_MATH_H
                        * and #include <math.h> */
#include <float.h>

/* Setting _LIB_VERSION to anything but _IEEE_ will turn on
 * errno handling. */
_LIB_VERSION_TYPE _LIB_VERSION = _POSIX_;

int main (void)
@{
  /* Reset the FPU (possible previous FP problems).  */
  _clear87 ();
  _fpreset ();

  /* Run the test.  */
  errno = 0;
  assert(errno == 0);
  sqrt(-1.0);
  assert(errno == EDOM); /* this line should NOT cause
                          * the assertion to fail */

  return(0);
@}

@end example
@c -----------------------------------------------------------------------------
@node link, llabs, libm, Alphabetical List
@unnumberedsec link
@c From file ./posix/unistd/link.txh
@findex link
@subheading Syntax

@example
#include <unistd.h>

int link(const char *exists, const char *new);
@end example

@subheading Description

Because of limitations of MS-DOS, this function doesn't really link two
files together.  However, it simulates a real @code{link} by copying the
file at @var{exists} to @var{new}. 

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
link("foo.c", "foo.bak");
@end example

@c -----------------------------------------------------------------------------
@node llabs, lldiv, link, Alphabetical List
@unnumberedsec llabs
@c From file ./ansi/stdlib/llabs.txh
@findex llabs
@subheading Syntax

@example
#include <stdlib.h>

long long int llabs(long long x);
@end example

@subheading Description

This function takes the absolute value of @var{x}.  @xref{abs}.

@subheading Return Value

|@var{x}|


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable

@c -----------------------------------------------------------------------------
@node lldiv, llockf, llabs, Alphabetical List
@unnumberedsec lldiv
@c From file ./ansi/stdlib/lldiv.txh
@findex lldiv
@tindex lldiv_t@r{ type}
@subheading Syntax

@example
#include <stdlib.h>

lldiv_t lldiv(long long int numerator, long long int denominator);
@end example

@subheading Description

Returns the quotient and remainder of the division @var{numerator}
divided by @var{denominator}.  The return type is as follows:

@example
typedef struct @{
  long long int quot;
  long long int rem;
@} lldiv_t;
@end example

@subheading Return Value

The results of the division are returned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable


@subheading Example

@example
lldiv_t l = lldiv(42, 3);
printf("42 = %lld x 3 + %lld\n", l.quot, l.rem);

lldiv(+40, +3) = @{ +13, +1 @}
lldiv(+40, -3) = @{ -13, +1 @}
lldiv(-40, +3) = @{ -13, -1 @}
lldiv(-40, -3) = @{ +13, -1 @}

@end example

@c -----------------------------------------------------------------------------
@node llockf, llrint, lldiv, Alphabetical List
@unnumberedsec llockf
@c From file ./compat/unistd/llockf.txh
@findex llockf
@subheading Syntax

@example
#include <unistd.h>

int llockf (int fildes, int function, offset_t size);
@end example

@subheading Description

The @code{llockf} function is a simplified interface to the locking
facilities of @code{fcntl} (see @ref{fcntl}, for more detailed
information).

The @code{llockf} function performs exactly the same functions as
@code{lockf} (@pxref{lockf}), with exactly the same input commands
and results, but the input @var{size} parameter is of type
@code{offset_t} instead of @code{off_t}, and the @code{fcntl} calls are
made using functions @code{F_GETLK64}, @code{F_SETLK64} and
@code{F_SETLKW64}, where @code{lockf} uses functions @code{F_GETLK},
@code{F_SETLK} and @code{F_SETLKW}.

The @code{llockf} function is intended to permit using @code{fcntl}
functions with @var{size} values greater than @math{2^31 - 1}.

@var{fildes} is an open file descriptor.

@var{function} is a control value which specifies the action to be
taken.  The permissible values for function are defined in <unistd.h> as
follows:

@smallexample
#define   F_ULOCK   0   /* Unlock a previously locked section */
#define   F_LOCK    1   /* Lock a section for exclusive use */
#define   F_TLOCK   2   /* Test and lock a section for exclusive use */
#define   F_TEST    3   /* Test section for other locks */
@end smallexample

All other values of @var{function} are reserved for future extensions
and will result in an error return if not implemented, with @code{errno}
set to @code{EINVAL}.

@var{size} is the number of contiguous bytes to be locked or unlocked.
The resource to be locked starts at the current offset in the file and
extends forward for a positive @var{size} and backward for a negative
@var{size} (the preceding bytes up to but not including the current
offset).  If @var{size} is zero, the section from the current offset
through the largest file offset is locked (i.e.@: from the current offset
through the end of file).

The functions defined for @code{llockf} are as follows:

@table @code
@item F_TEST
This function is used to detect if the specified section is already
locked.

@item F_LOCK
@itemx F_TLOCK
@code{F_LOCK} and @code{F_TLOCK} both lock a section of a file, if the
section is available.  These two function requests differ only by the
action taken if the resource is not available.  @code{F_LOCK} will cause
the calling program to wait until the resource is available.
@code{F_TLOCK} will cause the function to return a -1 and set
@code{errno} to @code{EACCES} if the section is already locked.

@item F_ULOCK
@code{F_ULOCK} removes locks from a section of the file. This function
will release locked sections controlled by the program.
@end table

The @code{llockf} function will fail, returning -1 and setting
@code{errno} to the following error values if the associated condition
is true:

@table @code
@item EBADF
Parameter @var{fildes} is not a valid open file.

@item EACCES
Parameter @var{function} is @code{F_TLOCK} or @code{F_TEST} and the
section is already locked.

@item EINVAL
Parameter @var{function} is not one of the implemented functions.
Or: An attempt was made to lock a directory, which is not supported.
@end table

All lock requests in this implementation are coded as exclusive locks
(i.e.@: all locks use the @code{fcntl} request @code{F_WRLCK}).

It is therefore wise to code @code{llockf} by using function
@code{F_TLOCK} with all lock requests, and to test the return value to
determine if the lock was obtained or not.  Using @code{F_TLOCK} will
cause the implementation to use @code{F_SETLK} instead of
@code{F_SETLKW}, which will return an error if the lock cannot be
obtained.


@subheading Return Value

On success, zero is returned.  On error, -1 is returned, and
@code{errno} is set appropriately, as described above.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
 /* Request a lock on file handle fd from the current position to
    the end of the file */
  errno = 0;
  retval = llockf(fd, F_LOCK, 0);

 /* Request a non-blocking lock on file handle fd */
  errno = 0;
  retval = llockf(fd, F_TLOCK, 0);

 /* Test a lock on file handle fd */
  errno = 0;
  retval = llockf(fd, F_TEST, 0);

 /* Release a lock on file handle fd */
  errno = 0;
  retval = llockf(fd, F_ULOCK, 0);
@end example
@c -----------------------------------------------------------------------------
@node llrint, llrintf, llockf, Alphabetical List
@unnumberedsec llrint
@c From file ./c99/math/llrint.txh
@vindex llrint
@subheading Syntax

@example
#include <math.h>

long long int llrint(double x);
@end example

@subheading Description

The @code{llrint} functions round their argument to the nearest integer value,
using the current rounding direction.

Note that unlike @code{rint}, etc., the return type of these functions differs
from that of their arguments.

The function do not set @code{errno}.

@subheading Return Value

Which floating-point error reporting methods are available.
The function returns the rounded integer value of @var{x}.
If @var{x} is @code{NaN} or an infinity, or the rounded value
is too large to be stored in a long then a domain error occurs,
and the return value is unspecified.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
long long int result = llrint(3.1415926535897932384626433832795);
@end example
@c -----------------------------------------------------------------------------
@node llrintf, llrintl, llrint, Alphabetical List
@unnumberedsec llrintf
@c From file ./c99/math/llrintf.txh
@vindex llrintf
@subheading Syntax

@example
#include <math.h>

long long int llrintf(float x);
@end example

@subheading Description

The @code{llrintf} functions round their argument to the nearest integer value,
using the current rounding direction.

Note that unlike @code{rint}, etc., the return type of these functions differs
from that of their arguments.

The function do not set @code{errno}.

@subheading Return Value

Which floating-point error reporting methods are available.
The function returns the rounded integer value of @var{x}.
If @var{x} is @code{NaN} or an infinity, or the rounded value
is too large to be stored in a long then a domain error occurs,
and the return value is unspecified.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
long long int result = llrintf(3.1415926535897932384626433832795);
@end example
@c -----------------------------------------------------------------------------
@node llrintl, llseek, llrintf, Alphabetical List
@unnumberedsec llrintl
@c From file ./c99/math/llrintl.txh
@vindex llrintl
@subheading Syntax

@example
#include <math.h>

long long int llrintl(long double x);
@end example

@subheading Description

The @code{llrintl} functions round their argument to the nearest integer value,
using the current rounding direction.

Note that unlike @code{rint}, etc., the return type of these functions differs
from that of their arguments.

The function do not set @code{errno}.

@subheading Return Value

Which floating-point error reporting methods are available.
The function returns the rounded integer value of @var{x}.
If @var{x} is @code{NaN} or an infinity, or the rounded value
is too large to be stored in a long then a domain error occurs,
and the return value is unspecified.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
long long int result = llrintl(3.1415926535897932384626433832795);
@end example
@c -----------------------------------------------------------------------------
@node llseek, load_npx, llrintl, Alphabetical List
@unnumberedsec llseek
@c From file ./compat/unistd/llseek.txh
@findex llseek
@subheading Syntax

@example
#include <unistd.h>

offset_t llseek(int fd, offset_t offset, int whence);
@end example

@subheading Description

This function moves the file pointer for @var{fd} according to
@var{whence}:

@table @code

@item SEEK_SET

The file pointer is moved to the offset specified.

@item SEEK_CUR

The file pointer is moved relative to its current position.

@item SEEK_END

The file pointer is moved to a position @var{offset} bytes from the end
of the file.  The offset is usually nonpositive in this case. 

@end table

@var{offset} is of type long long, thus enabling you to seek with
offsets as large as ~2^63 (FAT16 limits this to ~2^31; FAT32 limits
this to 2^32-2).

@subheading Return Value

The new offset is returned. Note that due to limitations in the
underlying DOS implementation the offset wraps around to 0 at offset
2^32. -1 means the call failed.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
long long ret;

ret = llseek(fd, (1<<32), SEEK_SET); /* Now ret equals 0
                                      * (unfortunately). */
ret = llseek(fd, -1, SEEK_CUR); /* Now ret equals 2^32-1 (good!). */
ret = llseek(fd, 0, SEEK_SET); /* Now ret equals 0 (good!). */
ret = llseek(fd, -1, SEEK_CUR); /* Now ret equals 2^32-1 (bad). */
@end example

@c -----------------------------------------------------------------------------
@node load_npx, localeconv, llseek, Alphabetical List
@unnumberedsec load_npx
@c From file ./debug.txh
@findex load_npx
@subheading Syntax

@example
#include <debug/dbgcom.h>

extern NPX npx;
void load_npx (void);
@end example

@subheading Description

This function restores the state of the x87 numeric processor from the
data saved in the external variable @code{npx}.  This variable is a
structure defined as follows in the header @file{debug/dbgcom.h}:

@example
typedef struct @{
  unsigned short sig0;
  unsigned short sig1;
  unsigned short sig2;
  unsigned short sig3;
  unsigned short exponent:15;
  unsigned short sign:1;
@} NPXREG;

typedef struct @{
  unsigned long control;
  unsigned long status;
  unsigned long tag;
  unsigned long eip;
  unsigned long cs;
  unsigned long dataptr;
  unsigned long datasel;
  NPXREG reg[8];
  long double st[8];
  char st_valid[8];
  long double mmx[8];
  char in_mmx_mode;
  char top;
@} NPX;
@end example

@code{load_npx} should be called immediately after @code{run_child}
(@pxref{run_child}) is called to begin or resume the debugged program,
and provided that a call to @code{save_npx} was issued before
@code{run_child} was called.  @xref{save_npx}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
 save_npx ();
 run_child ();
 load_npx ();
@end example

@c -----------------------------------------------------------------------------
@node localeconv, localtime, load_npx, Alphabetical List
@unnumberedsec localeconv
@c From file ./ansi/locale/lconv.txh
@findex localeconv
@tindex lconv@r{ structure}
@subheading Syntax

@example
#include <locale.h>

struct lconv *localeconv(void);
@end example

@subheading Description

This function returns a pointer to a static structure that contains
information about the current locale.  The structure contains these
fields:

@table @code

@item char *currency_symbol

A string that should be used when printing local currency.

@item char *decimal_point

A string that is used to separate the integer and fractional portions
of real numbers in @code{printf}.  Currently, only the first character
is significant.

@item char *grouping

An array of numbers indicating the size of groupings for non-monetary
values to the left of the decimal point.  The first number is the size
of the grouping just before the decimal point.  A number of zero means
to repeat the previous number indefinitely.  A number of @code{CHAR_MAX}
means to group the remainder of the digits together.

@item char *int_curr_symbol

A string that should be used when formatting monetary values for local
currency when the result will be used internationally.

@item char *mon_decimal_point

A string that separates the integer and fractional parts of monetary
values.

@item char *mon_grouping

Same as grouping, but for monetary values.

@item char *negative_sign

A string that is used to represent negative monetary values.

@item char *positive_sign

A string that is used to represent positive monetary values.

@item char *thousands_sep

The grouping separator for non-monetary values.

@item char frac_digits

The number of digits to the right of the decimal point for monetary
values.

@item char int_frac_digits

Like frac_digits, but when formatting for international use.

@item char n_cs_precedes

If nonzero, the currency string should precede the monetary value if
the monetary value is negative.

@item char n_sep_by_space

If nonzero, the currency string and the monetary value should be
separated by a space if the monetary value is negative.

@item char n_sign_posn

Determines the placement of the negative indication string if the
monetary value is negative.

@table @asis
@item 0
($value), (value$)
@item 1
-$value, -value$
@item 2
$value-, value$-
@item 3
-$value, value-$
@item 4
$-value, value$-
@end table

@item char p_cs_precedes
@item char p_sep_by_space
@item char p_sign_posn

These are the same as n_*, but for when the monetary value is
positive.

@end table

Note that any numeric field may have a value of @code{CHAR_MAX}, which
indicates that no information is available.

@subheading Return Value

A pointer to the @code{struct lconv} structure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
struct lconv *l = localeconv;
printf("%s%d\n", l->negative_sign, value);
@end example

@c -----------------------------------------------------------------------------
@node localtime, localtime_r, localeconv, Alphabetical List
@unnumberedsec localtime
@c From file ./ansi/time/ctime.txh
@findex localtime
@subheading Syntax

@example
#include <time.h>

struct tm *localtime(const time_t *tod);
@end example

@subheading Description

Converts the time represented by @var{tod} into a structure, correcting
for the local timezone.  @xref{gmtime}, for the description of
@code{struct tm}.

The structure pointed to is static and will be overwritten with
each call to @code{localtime}.
The structure should be copied if it needs to be preserved.
@xref{localtime_r}, for an alternate interface that allows the caller
to provide the structure to be filled.

@subheading Return Value

A pointer to a static structure which is overwritten with each call. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node localtime_r, lock, localtime, Alphabetical List
@unnumberedsec localtime_r
@c From file ./ansi/time/ctime.txh
@findex localtime_r
@subheading Syntax

@example
#include <time.h>

struct tm *localtime_r(const time_t * restrict tod, struct tm * restrict tptr);
@end example

@subheading Description

Converts the time represented by @var{tod} into structure @var{tptr},
correcting for the local timezone.

@xref{gmtime}, for the description of @code{struct tm}.

@xref{localtime}, for an alternate ISO Standard interface.

@subheading Return Value

A pointer to @var{tptr} containing the broken down calendar time.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node lock, lock64, localtime_r, Alphabetical List
@unnumberedsec lock
@c From file ./dos/io/lock.txh
@findex lock
@subheading Syntax

@example
#include <io.h>

int lock(int fd, long offset, long length);
@end example

@subheading Description
Locks a region in file @var{fd} using MS-DOS file sharing interface.
The region of @var{length} bytes, starting from @var{offset}, will
become entirely inaccessible to other processes.  If multiple locks
are used on a single file they must be non-overlapping.  The lock
must be removed before the file is closed.

This function will fail unless @code{share}, or a network software
providing similar interface, is installed.  This function is
compatible with Borland C@t{++} function of the same name.

@xref{unlock}.

@subheading Return Value
Zero if successful, nonzero if not.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node lock64, lockf, lock, Alphabetical List
@unnumberedsec lock64
@c From file ./dos/io/lock64.txh
@findex lock64
@subheading Syntax

@example
#include <io.h>

int lock64(int fd, long long offset, long long length);
@end example

@subheading Description
Locks a region in file @var{fd} using MS-DOS file sharing interface.
The region of @var{length} bytes, starting from @var{offset}, will
become entirely inaccessible to other processes.  If multiple locks are
used on a single file they must be non-overlapping.  The lock must be
removed before the file is closed.

This function will fail unless SHARE, or a network software providing
similar interface, is installed.

Arguments @var{offset} and @var{length} must be of type @code{long
long}, thus enabling you to lock with offsets and lengths as large as
~@math{2^63} (FAT16 limits this to ~@math{2^31}; FAT32 limits this to
@math{2^32-2}).

@xref{unlock64}.

@subheading Return Value
Zero if successful, nonzero if not.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node lockf, log, lock64, Alphabetical List
@unnumberedsec lockf
@c From file ./compat/unistd/lockf.txh
@findex lockf
@subheading Syntax

@example
#include <unistd.h>

int lockf (int fildes, int function, off_t size);
@end example

@subheading Description

The @code{lockf} function is a simplified interface to the locking
facilities of @code{fcntl} (see @ref{fcntl}, for more detailed
information).

@var{fildes} is an open file descriptor.

@var{function} is a control value which specifies the action to be
taken.  The permissible values for function are defined in <unistd.h> as
follows:

@smallexample
#define   F_ULOCK   0   /* Unlock a previously locked section */
#define   F_LOCK    1   /* Lock a section for exclusive use */
#define   F_TLOCK   2   /* Test and lock a section for exclusive use */
#define   F_TEST    3   /* Test section for other locks */
@end smallexample

All other values of @var{function} are reserved for future extensions
and will result in an error return if not implemented, with @code{errno}
set to @code{EINVAL}.

@var{size} is the number of contiguous bytes to be locked or unlocked.
The resource to be locked starts at the current offset in the file and
extends forward for a positive @var{size} and backward for a negative
@var{size} (the preceding bytes up to but not including the current
offset).  If @var{size} is zero, the section from the current offset
through the largest file offset is locked (i.e.@: from the current offset
through the end of file).

The functions defined for @code{lockf} are as follows:

@table @code
@item F_TEST
This function is used to detect if the specified section is already
locked.

@item F_LOCK
@itemx F_TLOCK
@code{F_LOCK} and @code{F_TLOCK} both lock a section of a file, if the
section is available.  These two function requests differ only by the
action taken if the resource is not available.  @code{F_LOCK} will cause
the calling program to wait until the resource is available.
@code{F_TLOCK} will cause the function to return a -1 and set
@code{errno} to @code{EACCES} if the section is already locked.

@item F_ULOCK
@code{F_ULOCK} removes locks from a section of the file.  This function
will release locked sections controlled by the program.
@end table

The @code{lockf} function will fail, returning -1 and setting
@code{errno} to the following error values if the associated condition
is true:

@table @code
@item EBADF
Parameter @var{fildes} is not a valid open file.

@item EACCES
Parameter @var{function} is @code{F_TLOCK} or @code{F_TEST} and the
section is already locked.

@item EINVAL
Parameter @var{function} is not one of the implemented functions.
Or: An attempt was made to lock a directory, which is not supported.
@end table

All lock requests in this implementation are coded as exclusive locks
(i.e.@: all locks use the @code{fcntl} request @code{F_WRLCK}).

It is therefore wise to code @code{lockf} by using function
@code{F_TLOCK} with all lock requests, and to test the return value to
determine if the lock was obtained or not.  Using @code{F_TLOCK} will
cause the implementation to use @code{F_SETLK} instead of
@code{F_SETLKW}, which will return an error if the lock cannot be
obtained.


@subheading Return Value

On success, zero is returned.  On error, -1 is returned, and
@code{errno} is set appropriately, as described above.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
 /* Request a lock on file handle fd from the current position to
    the end of the file */
  errno = 0;
  retval = lockf(fd, F_LOCK, 0);

 /* Request a non-blocking lock on file handle fd */
  errno = 0;
  retval = lockf(fd, F_TLOCK, 0);

 /* Test a lock on file handle fd */
  errno = 0;
  retval = lockf(fd, F_TEST, 0);

 /* Release a lock on file handle fd */
  errno = 0;
  retval = lockf(fd, F_ULOCK, 0);
@end example
@c -----------------------------------------------------------------------------
@node log, log10, lockf, Alphabetical List
@unnumberedsec log
@c From file ./ansi/math/log.txh
@findex log
@subheading Syntax

@example
#include <math.h>

double log(double x);
@end example

@subheading Description

This function computes the natural logarithm of @var{x}.

@subheading Return Value

The natural logarithm of @var{x}.  If @var{x} is zero, a negative
infinity is returned and @code{errno} is set to @code{ERANGE}.  If
@var{x} is negative or @code{+Inf} or a @code{NaN}, the return value is
@code{NaN} and @code{errno} is set to @code{EDOM}.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node log10, log1p, log, Alphabetical List
@unnumberedsec log10
@c From file ./ansi/math/log10.txh
@findex log10
@subheading Syntax

@example
#include <math.h>

double log10(double x);
@end example

@subheading Description

This function computes the base-10 logarithm of @var{x}.

@subheading Return Value

The logarithm base 10 of @var{x}.  If @var{x} is zero, a negative
infinity is returned and @code{errno} is set to @code{ERANGE}.  If
@var{x} is negative or @code{+Inf} or a @code{NaN}, the return value is
@code{NaN} and @code{errno} is set to @code{EDOM}.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node log1p, log2, log10, Alphabetical List
@unnumberedsec log1p
@c From file ./compat/math/log1p.txh
@findex log1p
@subheading Syntax

@example
#include <math.h>

double log1p(double x);
@end example

@subheading Description

This function computes the natural logarithm of @math{1 + @var{x}}.  It
is more accurate than @samp{log(1 + @var{x})} for small values of
@var{x}.

@subheading Return Value

The natural logarithm of @math{1 + @var{x}}.  If @var{x} is -1, a
negative infinity is returned and @code{errno} is set to @code{ERANGE}.
If @var{x} is less than -1 or @code{+Inf} or a @code{NaN}, the return
value is @code{NaN} and @code{errno} is set to @code{EDOM}.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node log2, longjmp, log1p, Alphabetical List
@unnumberedsec log2
@c From file ./compat/math/log2.txh
@findex log2
@subheading Syntax

@example
#include <math.h>

double log2(double x);
@end example

@subheading Description

This function computes the base-2 logarithm of @var{x}.

@subheading Return Value

The base-2 logarithm of @var{x}.  If @var{x} is zero, a negative
infinity is returned and @code{errno} is set to @code{ERANGE}.  If
@var{x} is negative or @code{+Inf} or a @code{NaN}, the return value is
@code{NaN} and @code{errno} is set to @code{EDOM}.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node longjmp, lowvideo, log2, Alphabetical List
@unnumberedsec longjmp
@c From file ./ansi/setjmp/longjmp.txh
@findex longjmp
@subheading Syntax

@example
#include <setjmp.h>

void longjmp(jmp_buf env, int val);
@end example

@subheading Description

This function reverts back to a CPU state that was stored in @var{env}
by @code{setjmp} (@pxref{setjmp}).  The state includes all CPU registers,
so any variable in a register when @code{setjmp} was called will be
preserved, and all else will be indeterminate.

The value passed as @var{val} will be the return value of @code{setjmp}
when it resumes processing there.  If @var{val} is zero, the return
value will be one. 

@subheading Return Value

This function does not return.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
jmp_buf j;
if (setjmp(j))
  return;
do_something();
longjmp(j, 1);
@end example

@c -----------------------------------------------------------------------------
@node lowvideo, lrint, longjmp, Alphabetical List
@unnumberedsec lowvideo
@c From file ./pc_hw/co80/conio.txh
@findex lowvideo
@subheading Syntax

@example
#include <conio.h>

void    lowvideo(void);
@end example

@subheading Description

Causes any new characters put on the screen to be dim.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node lrint, lrintf, lowvideo, Alphabetical List
@unnumberedsec lrint
@c From file ./c99/math/lrint.txh
@vindex lrint
@subheading Syntax

@example
#include <math.h>

long int lrint(double x);
@end example

@subheading Description

The @code{lrint} functions round their argument to the nearest integer value,
using the current rounding direction.

Note that unlike @code{rint}, etc., the return type of these functions differs
from that of their arguments.

The function do not set @code{errno}.

@subheading Return Value

Which floating-point error reporting methods are available.
The function returns the rounded integer value of @var{x}.
If @var{x} is @code{NaN} or an infinity, or the rounded value
is too large to be stored in a long then a domain error occurs,
and the return value is unspecified.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
long int result = lrint(3.1415926535897932384626433832795);
@end example
@c -----------------------------------------------------------------------------
@node lrintf, lrintl, lrint, Alphabetical List
@unnumberedsec lrintf
@c From file ./c99/math/lrintf.txh
@vindex lrintf
@subheading Syntax

@example
#include <math.h>

long int lrintf(float x);
@end example

@subheading Description

The @code{lrintf} functions round their argument to the nearest integer value,
using the current rounding direction.

Note that unlike @code{rint}, etc., the return type of these functions differs
from that of their arguments.

The function do not set @code{errno}.

@subheading Return Value

Which floating-point error reporting methods are available.
The function returns the rounded integer value of @var{x}.
If @var{x} is @code{NaN} or an infinity, or the rounded value
is too large to be stored in a long then a domain error occurs,
and the return value is unspecified.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
long int result = lrintf(3.1415926535897932384626433832795);
@end example
@c -----------------------------------------------------------------------------
@node lrintl, lsearch, lrintf, Alphabetical List
@unnumberedsec lrintl
@c From file ./c99/math/lrintl.txh
@vindex lrintl
@subheading Syntax

@example
#include <math.h>

long int lrintl(long double x);
@end example

@subheading Description

The @code{lrintl} functions round their argument to the nearest integer value,
using the current rounding direction.

Note that unlike @code{rint}, etc., the return type of these functions differs
from that of their arguments.

The function do not set @code{errno}.

@subheading Return Value

Which floating-point error reporting methods are available.
The function returns the rounded integer value of @var{x}.
If @var{x} is @code{NaN} or an infinity, or the rounded value
is too large to be stored in a long then a domain error occurs,
and the return value is unspecified.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
long int result = lrintl(3.1415926535897932384626433832795);
@end example
@c -----------------------------------------------------------------------------
@node lsearch, lseek, lrintl, Alphabetical List
@unnumberedsec lsearch
@c From file ./posix/search/lfind.txh
@findex lsearch
@subheading Syntax

@example
#include <search.h>

void * lsearch(const void *key, void *base, size_t *nelp, size_t width, 
               int (*compar)(const void *, const void *));
@end example

@subheading Description

This function searches the array @var{base} of elements of size
@var{width}, currently containing @var{nelp} elements, for the element
identified by @var{key} using the comparison function @var{compar}.  

If the @var{key} isn't found it is added to the array @var{base} and
@var{*nelp} is incremented.  

The function @var{compar} should return 0 when its inputs are equal
and not 0 otherwise.  

It is the caller's responsibility that the array has enough room for
an additional element.  

See also @code{lfind} (@pxref{lfind}).  

@subheading Return Value

A pointer to the found or inserted element.  

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
#include <search.h>
#include <stdio.h>
#include <string.h>

#define N_ELEM       50
#define ELEM_SIZE    sizeof(char *)
#define COMPARE_FUN  my_p_strcmp

char *arr[N_ELEM];
size_t n_arr = 0;


int my_p_strcmp( const void *el1, const void *el2)
@{
  return strcmp( *(const char **)el1, *(const char **)el2 );
@}


int main(void)
@{
  const char *nentry;
  char *entry;

  nentry = "Anyone there?";
  entry = lsearch(&nentry, arr, &n_arr, ELEM_SIZE, COMPARE_FUN);
  if( entry )
  @{
    printf("Someone there: %s, %ld\n", entry, n_arr);
  @}
  else
  @{
    printf("Error, noone there: %ld...\n", n_arr);
  @}

  return 0;
@}

@end example
@c -----------------------------------------------------------------------------
@node lseek, lstat, lsearch, Alphabetical List
@unnumberedsec lseek
@c From file ./posix/unistd/lseek.txh
@findex lseek
@subheading Syntax

@example
#include <unistd.h>

off_t lseek(int fd, off_t offset, int whence);
@end example

@subheading Description

This function moves the file pointer for handle @var{fd} according to
@var{whence}:

@table @code

@item SEEK_SET

The file pointer is moved to the @var{offset} specified.

@item SEEK_CUR

The file pointer is moved @var{offset} bytes relative to its current
position.

@item SEEK_END

The file pointer is moved to a position @var{offset} bytes from the end
of the file.  The value of @var{offset} is usually nonpositive in this
case. 

@end table

@subheading Return Value

The new offset is returned, or -1 and @code{errno} set on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
lseek(fd, 12, SEEK_CUR); /* skip 12 bytes */
@end example

@c -----------------------------------------------------------------------------
@node lstat, malldbgdmpfile, lseek, Alphabetical List
@unnumberedsec lstat
@c From file ./posix/sys/stat/lstat.txh
@findex lstat
@subheading Syntax

@example
#include <sys/stat.h>

int lstat(const char *file, struct stat *sbuf);
@end example

@subheading Description

This function obtains the status of the file @var{file} and stores
it in @var{sbuf}.  If @var{file} is a symbolic link, then @code{lstat}
returns information about the symbolic link.  To get information about
the target of a symbolic link, use @code{stat} (@pxref{stat}) instead.

@var{sbuf} has this structure:

@smallexample
struct  stat @{
        time_t    st_atime;     /* time of last access       */
        time_t    st_ctime;     /* time of file's creation   */
        dev_t     st_dev;       /* The drive number (0 = a:) */
        gid_t     st_gid;       /* what getgid() returns */
        ino_t     st_ino;       /* starting cluster or unique identifier */
        mode_t    st_mode;      /* file mode - S_IF* and S_IRUSR/S_IWUSR */
        time_t    st_mtime;     /* time that the file was last written */
        nlink_t   st_nlink;     /* 2 + number of subdirs, or 1 for files */
        off_t     st_size;      /* size of file in bytes */
	blksize_t st_blksize;   /* block size in bytes*/
        uid_t     st_uid;       /* what getuid() returns */
	dev_t     st_rdev;      /* The drive number (0 = a:) */
@};
@end smallexample

The @code{st_atime}, @code{st_ctime} and @code{st_mtime} have different
values only when long file names are supported (e.g. on Windows 9X);
otherwise, they all have the same value: the time that the file was last
written@footnote{
Even when long file names @emph{are} supported, the three time values
returned by @code{lstat} might be identical if the file was last written
by a program which used legacy DOS functions that don't know about long
file names.}.  Most Windows 9X VFAT filesystems only support the date of
the file's last access (the time is set to zero); therefore, the DJGPP
implementation of @code{lstat} sets the @code{st_atime} member to the
same value as @code{st_mtime} if the time part of @code{st_atime}
returned by the filesystem is zero (to prevent the situation where the
file appears to have been created @emph{after} it was last accessed,
which doesn't look good).

The @code{st_size} member is an signed 32-bit integer type, so it will
overflow on FAT32 volumes for files that are larger than 2GB.
Therefore, if your program needs to support large files, you should
treat the value of @code{st_size} as an unsigned value.

For some drives @code{st_blksize} has a default value, to improve
performance.  The floppy drives A: and B: default to a block size
of 512 bytes.  Network drives default to a block size of 4096 bytes.

Some members of @code{struct stat} are very expensive to compute.  If
your application is a heavy user of @code{lstat} and is too slow, you can
disable computation of the members your application doesn't need, as
described in @ref{_djstat_flags}.

@subheading Return Value

Zero on success, nonzero on failure (and @code{errno} set).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
struct stat s;
lstat("data.txt", &s);
if (S_ISDIR(s.st_mode))
  printf("is directory\n");
@end example

@subheading Implementation Notes

Supplying a 100% Unix-compatible @code{lstat} function under DOS is an
implementation nightmare.  The following notes describe some of the
obscure points specific to @code{lstat}s behavior in DJGPP.

1. The @samp{drive} for character devices (like @code{con}, @code{/dev/null}
and others is returned as -1.  For drives networked by Novell Netware, it
is returned as -2.

2. The starting cluster number of a file serves as its inode number.  For
files whose starting cluster number is inaccessible (empty files, files on
Windows 9X, on networked drives, etc.) the @code{st_inode} field will be
@emph{invented}
in a way which guarantees that no two different files will get the same
inode number (thus it is unique).  This invented inode will also be
different from any real cluster number of any local file.  However, only
on plain DOS, and only for local, non-empty files/directories the inode
is guaranteed to be consistent between @code{stat}, @code{fstat} and 
@code{lstat} function calls.  (Note that two files whose names are
identical but for the drive letter, will get the same invented inode,
since each filesystem has its own independent inode numbering, and
comparing files for identity should include the value of @code{st_dev}.)

3. The WRITE access mode bit is set only for the user (unless the file is
read-only, hidden or system).  EXECUTE bit is set for directories,  files
which can be executed from the DOS prompt (batch files, .com, .dll and .exe
executables) or run by @code{go32-v2}.

4. Size of directories is reported as the number of its files (sans `.' and
`..' entries) multiplied by 32 bytes (the size of directory entry).  On FAT
filesystems that support the LFN API (such as Windows 9X), the reported
size of the directory accounts for additional space used to store the long
file names.

5. Time stamp for root directories is taken from the volume label entry,
if that's available; otherwise, it is reported as 1-Jan-1980.

6. The variable @code{_djstat_flags} (@pxref{_djstat_flags}) controls
what hard-to-get fields of @code{struct stat} are needed by the
application.

7. @code{lstat} should not be used to get an up-to-date info about a file
which is open and has been written to, because @code{lstat} will only
return correct data after the file is closed.  Use @code{fstat}
(@pxref{fstat}) while the file is open.  Alternatively, you can call
@code{fflush} and @code{fsync} to make the OS flush all the file's data
to the disk, before calling @code{lstat}.

8. The number of links @code{st_nlink} is always 1 for files other than
directories.  For directories, it is the number of subdirectories plus
2.  This is so that programs written for Unix that depend on this to
optimize recursive traversal of the directory tree, will still work.
@c -----------------------------------------------------------------------------
@node malldbgdmpfile, malldbgdumpfile, lstat, Alphabetical List
@unnumberedsec malldbgdmpfile
@c From file ./ansi/stdlib/nmalloc.txh
@subheading Syntax

@example
#include <stdlib.h>
#include <malldbg.h> (on non-DJGPP systems)

FILE *malldbgdmpfile(FILE *fp);
@end example

@subheading Description

This function allows diverting the output of the malldbg package
to any suitable text file, known as the @dfn{dumpfile}.  By
default the package uses @code{stderr}.

@subheading Return Value

The previous identity of the dumpfile.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


This function is specific to DJGPP.

@subheading Example

@example
FILE *oldfile = malldbgdmpfile(stdout);
@end example


@c -----------------------------------------------------------------------------
@node malldbgdumpfile, mallinfo, malldbgdmpfile, Alphabetical List
@unnumberedsec malldbgdumpfile
@c From file ./ansi/stdlib/nmalloc.txh

@subheading Syntax

@example
  FILE *fNew = fopen("mallocdbg.out", "w");
  FIKE *fOld = malldbgdumpfile(fNew);
@end example

@subheading Description

Specifies the file used by memory allocation debug functions

@subheading Return Value

Returns file used earlier (before call) for this purpose.
Initial value of output file is stderr.

@subheading Portability
@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable



@c -----------------------------------------------------------------------------
@node mallinfo, malloc, malldbgdumpfile, Alphabetical List
@unnumberedsec mallinfo
@c From file ./ansi/stdlib/nmalloc.txh
@subheading Syntax

@example
#include <stdlib.h>
#include <malldbg.h> /* on non-DJGPP systems */

struct mallinfo mallinfo(void);
@end example

@subheading Description

This function returns information about heap space usage.  It is
intended to be used for debugging dynamic memory allocation and
tracking heap usage.  The @code{struct mallinfo} structure is
defined by @file{stdlib.h} as follows:

@example
 struct mallinfo @{
   int arena;
   int ordblks;
   int smblks;
   int hblks;
   int hblkhd;
   int usmblks;
   int fsmblks;
   int uordblks;
   int fordblks;
   int keepcost;
 @};
@end example

@noindent
whose members are:

@table @code
@item arena
The total amount of space, in bytes, handed by @code{sbrk} to
@code{malloc}.  Note that this is not the same as
@code{sbrk(0)}, since @code{sbrk} allocates memory in large
chunks and then subdivides them and passes them to @code{malloc}
as required.  In particular, the result of @code{sbrk(0)} might
be much larger than the @code{arena} member of @code{struct
mallinfo} when the DPMI host allocates memory in non-contiguous
regions (happens on MS-Windows).

@item ordblks
The number of ``ordinary blocks'': the total number of allocated
and free blocks maintained by @code{malloc}.

@item smblks
The number of ``small blocks''.  This is normally zero, unless
a special version of @code{malloc} was installed.

@item hblks
The count of freeblocks maintained in the malloc arena.  This
is normally much smaller than the number of freed blocks, since
such blocks have been combined into larger blocks.

@item hblkhd
The size of the currently available top portion of the memory
assigned by @code{sbrk}.  Sometimes known as @dfn{slop}.

@item usmblks
The space (in bytes) in ``small blocks'' that are in use.  This
is always zero in the DJGPP implementation.

@item fsmblks
The space in free ``small blocks''.  Normally zero in the DJGPP
implementation.

@item uordblks
The amount of space, in bytes, in the heap space currently used
by the application.  This does not include the small overhead
used by @code{malloc} to maintain its hidden information in each
allocated block.

@item fordblks
The amount of free heap space maintained by @code{malloc} in its
free list of hblks chunks.

@item keepcost
The total overhead used by @code{malloc} in maintaining the
currently allocated blocks.
@end table

@subheading Return Value

The @code{mallinfo} structure filled with information.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
This function is available on many Unix systems.
@end enumerate

@subheading Example

@example
 struct mallinfo info = mallinfo();

 printf("Memory in use: %d bytes\n",
        info.usmblks + info.uordblks);
 printf("Total heap size: %d bytes\n", info.arena);
@end example


@c -----------------------------------------------------------------------------
@node malloc, malloc_debug, mallinfo, Alphabetical List
@unnumberedsec malloc
@c From file ./ansi/stdlib/nmalloc.txh
@subheading Syntax

@example
#include <stdlib.h>

void *malloc(size_t size);
@end example

@subheading Description

This function allocates a chunk of memory from the heap large
enough to hold any object that is @var{size} bytes in length.
This memory must be returned to the heap with @code{free}
(@pxref{free}).

Note: excessively large requests are rejected.  At present
excessively large means over @code{INT_MAX} - 65536.

Note: this version of malloc is designed to reduce memory usage.
A faster but less efficient version is available in the libc
sources (@file{djlsr*.zip}) in the file
@file{src/libc/ansi/stdlib/fmalloc.c}.

@subheading Return Value

A pointer to the allocated memory, or @code{NULL} if there isn't
enough free memory to satisfy the request.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
char *c = malloc(100);
@end example


@c -----------------------------------------------------------------------------
@node malloc_debug, malloc_verify, malloc, Alphabetical List
@unnumberedsec malloc_debug
@c From file ./ansi/stdlib/nmalloc.txh
@subheading Syntax

@example
#include <stdlib.h>
#include <malldbg.h> /* on non-DJGPP systems */

int malloc_debug(int level);
@end example

@subheading Description
This function sets the level of error diagnosis and reporting
during subsequent calls to @code{malloc}, @code{free},
@code{realloc}, and all functions which call them internally.
The argument @var{level} is interpreted as follows:

@table @asis 
@item Level 0
The memory allocation functions behave as they do if
@code{malloc_debug} was never called.  Only passive checks are
allowed, including @code{malloc_verify}, @code{mallocmap}, and
@code{malldbgdumpfile} (to set the output file).  In particular
@code{mallsethook} is disabled, to avoid accidents.  The actual
functioning of the malloc system remains unaffected.  Any malloc
hooks set by @code{mallsethook} are reset. If errors are detected by
@code{malloc_verify}, it prints diagnostic messages to the
@dfn{dumpfile} (default standard error stream), with address
and size of the offending block and other pertinent information.

@item Level 1
All the passive checks of level 0 are allowed.  In addition
@code{mallsethook} is enabled, thus allowing construction of
custom debugging packages.

@item Level 2
Similar to level 1, but the consistency of the entire heap is
also verified (by calling @code{malloc_verify}) on every call to
the memory allocation functions.  @emph{Warning: this may
significantly slow down the application.}  Since the malloc
hooks are in use to connect to this system, @code{mallsethook}
is disabled.  If there are hooks already in use the change to
level 2 or above is rejected.

@item Level 3
Similar to level 2, except that the program is aborted whenever
a heap corruption is detected.  In addition, failed allocations
(i.e.@: when @code{malloc} or @code{realloc} returns @code{NULL}
because it cannot satisfy a request) are reported to the
dumpfile (default standard error).

@item Level 4
Similar to level 3, but calls to @code{free} with a @code{NULL}
pointer as an argument are also reported.

@item Level -1
Does not alter the debug level, but returns the current value.
@end table

@subheading Return Value

@code{malloc_debug} returns the previous error diagnostic level.  The
default level is 0.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
This function is available on many Unix systems.
@end enumerate

@subheading Example

@example
 malloc_debug(2);
 ...
 malloc_verify();
@end example


@c -----------------------------------------------------------------------------
@node malloc_verify, mallocmap, malloc_debug, Alphabetical List
@unnumberedsec malloc_verify
@c From file ./ansi/stdlib/nmalloc.txh
@subheading Syntax

@example
#include <stdlib.h>
#include <malldbg.h> /* on non-DJGPP systems */

int malloc_verify(void);
@end example

@subheading Description
This function attempts to determine if the heap has been
corrupted.  It scans all the blocks allocated by @code{malloc}
and handed to the application, and also all the free blocks
maintained by @code{malloc} and @code{free} in the internal free
list.  Each block is checked for consistency of the hidden
bookkeeping information recorded in it by @code{malloc} and
@code{free}.

What happens when a bad block is found depends on the current
@dfn{malloc diagnostics level}: for example, the block can be
reported, or the program may be aborted.  @xref{malloc_debug},
for the details.

@subheading Return Value
If the program isn't aborted during the function's run (this
depends on the current diagnostics level), @code{malloc_verify}
returns 1 if the heap passes all tests, or zero of some of the
tests failed.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
This function is available on many Unix systems.
@end enumerate

@subheading Example

@example
 if (malloc_verify() == 0)
   printf ("Heap corruption detected!\n");
@end example


@c -----------------------------------------------------------------------------
@node mallocmap, mallsethook, malloc_verify, Alphabetical List
@unnumberedsec mallocmap
@c From file ./ansi/stdlib/nmalloc.txh
@subheading Syntax

@example
#include <stdlib.h>
#include <malldbg.h> /* on non-DJGPP systems */

void mallocmap(void);
@end example

@subheading Description

This function prints a map of the heap storage to the selected
@file{dumpfile}. @xref{malldbgdumpfile}. For each block, its
address and size are printed, as well as an indication whether
it is free or in use, together with pointers to adjacent blocks.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
This function is available on many Unix systems.
@end enumerate


@c -----------------------------------------------------------------------------
@node mallsethook, math_errhandling, mallocmap, Alphabetical List
@unnumberedsec mallsethook
@c From file ./ansi/stdlib/nmalloc.txh
@subheading Syntax

@example
#include <stdlib.h>
#include <malldbg.h> /* on non-DJGPP systems */

M_HOOKFN mallsethook(enum m_hook_kind which,
                     M_HOOKFN newhook);
@end example

@subheading Description
Several @dfn{hooks} are provided for building custom
@code{malloc} debugging packages.  Such packages typically need
to be notified when memory is allocated and freed by the
application, in order to be able to find memory leaks, code that
writes beyond the limits of allocated buffers or attempts to
@code{free} buffers which were not allocated by @code{malloc},
etc. These hooks can be used to define callback functions which
will be called by the library at strategic points.  Each
callback is only called if it is non-@code{NULL}; by default,
all of them are initialized to a @code{NULL} value.

The actual hook to be set is described by the following
constants, enumerated in @file{stdlib.h}:

@table @code
@item malloc_HK = 0    
on entry to malloc

@item malloc_fail_HK   
when malloc or realloc fails

@item free_HK          
on entry to free

@item free_null_HK     
when free is called with a NULL pointer

@item realloc_HK       
on entry to realloc

@item realloc_exit_HK  
when realloc exits.

@item HKCOUNT          
The first invalid value for a hook descriptor.
@end table

@noindent
and each ``callback'' function is described by:

@example
   typedef void (*M_HOOKFN)(size_t sz, void *ptr);
@end example

@noindent
in @file{stdlib.h}.  Note that in some cases the parameters
supplied to the ``callback'' function will be meaningless, in
which case they will be zero or @code{NULL} as appropriate.  The
callback function must @strong{NOT} call any of @code{malloc},
@code{free}, or @code{realloc}.

@code{mallsethook} action is disabled unless the debug_level is
set to 1.  This interlock avoids accidental use before enabling
the package, and avoids altering hooks that are already in use
for debug_level of 2 or higher.

For access to the internal storage of the malloc arena, see the
@code{_sysmalloc} call and the @code{_sysinfo} struct.

@table @code

@item malloc_HK
Called just before a chunk of memory is about to be returned to
the application in response to an allocation request.
@var{sz} is the size requested by the application
(@strong{not} the actual size of the allocated buffer, which may
be larger).  @var{ptr} is a pointer to the block that was
allocated.

@item malloc_fail_HK
Called if @code{malloc} failed to find a free block large enough
to satisfy a request, and also failed to obtain additional
memory from @code{sbrk}.  @var{sz} is the requested allocation
size.

@item free_HK
Called when a buffer is about to be freed.  @var{ptr} is a
pointer to the block to be freed.  Its validity has not been
checked.

@item free_null_HK
Called whenever a @code{NULL} pointer is passed to @code{free}.
@acronym{ANSI} C specifically rules that this is allowed and
should have no effect, but you might want to catch such cases if
your program needs to be portable to old compilers whose
libraries don't like @code{NULL} pointers in @code{free}.

@item realloc_HK
Called at entry to @code{realloc}, before the actual
reallocation. @var{ptr} is the pointer whose contents are to be
reallocated.  @var{sz} is the new size requested by the
application.  (This hook is called @emph{in addition} to the
other hooks which may be called by @code{malloc} if and when
@code{realloc} calls them.)

@item realloc_exit_HK
Called at exit from @code{realloc}.  @var{sz} is the requested
size, and @var{ptr} is the (possibly) revised value of the user
pointer which will be returned by @code{realloc}.  This may be
@code{NULL} if realloc was unable to allocate the space, in
which case @emph{ONLY} the original value of @var{ptr} (as
reported by @code{realloc_HK}) remains valid.

@end table

@subheading Return Value

@code{mallsethook} returns the previous hook pointer, (usually
@code{NULL}). If @code{mallsethook} is disabled it will also
return @code{NULL}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


These hooks and the function are specific to DJGPP.

@subheading Example

@example

 static void mallocfailalert(size_t sz, void *ptr)
 @{
    printf("Failed to malloc %lu bytes\n", (unsigned long)sz);
 @}

 malloc_debug(1);
 mallsethook(malloc_fail_HK, mallocfailalert);
 ...
 /* any malloc failure will result in a message */
 
@end example


@c -----------------------------------------------------------------------------
@node math_errhandling, matherr, mallsethook, Alphabetical List
@unnumberedsec math_errhandling
@c From file ./c99/math/errhandl.txh
@vindex math_errhandling
@subheading Syntax

@example
#include <math.h>
@end example

@subheading Description

@code{math_errhandling} evaluates to an integer expression describing
the floating-point error reporting methods used by the C library.

If @code{math_errhandling} returns the bit @code{MATH_ERRNO} set,
then errors are reported using @code{errno} (@pxref{errno}).

If @code{math_errhandling} returns the bit @code{MATH_ERREXCEPT} set,
then errors are reported by raising ``exceptions''.

The library may support both methods of error reporting. Currently
DJGPP only supports reporting errors using @code{errno}.

@subheading Return Value

Which floating-point error reporting methods are available.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
if (math_errhandling & MATH_ERRNO)
  perror("myprogram");
@end example
@c -----------------------------------------------------------------------------
@node matherr, mblen, math_errhandling, Alphabetical List
@unnumberedsec matherr
@c From file ./pc_hw/fpu/s_mather.txh
@findex matherr
@tindex exception@r{ structure}
@subheading Syntax

@example
#include <libm/math.h>

enum fdversion _fdlib_version = _SVID_;

int matherr(struct exception *exc);
@end example

@subheading Description

@code{matherr} is a user-definable handler for errors in math library
functions.  It is only supported in the alternate math library (link
with @samp{-lm}), and will only be called if the global variable
@code{_fdlib_version} is set to either @code{_SVID_} or @code{_XOPEN_}
(@pxref{libm}).  You also need to mask the Invalid Operation exception
in the x87 control word (@pxref{_control87}) or install a handler for
signal @code{SIGFPE} (@pxref{signal}), or else some exceptions will
generate @code{SIGFPE} and your program will be terminated before it
gets a chance to call @code{matherr}.  DJGPP versions 2.02 and later
mask all FP exceptions at startup, so this consideration applies only to
programs that unmask FP exceptions at run time.

If the above conditions are met, every math function will call
@code{matherr} when a numerical exception is detected.  The default
version of @code{matherr}, supplied with @file{libm.a}, does nothing and
returns zero (the @code{_SVID_} version will then print an error message
to the standard error stream and set @code{errno}).

This default behavior is inappropriate in some cases.  For example, an
interactive program which runs in a windowed environment might want the
error message to go to a particular window, or pop up a dialog box; a
fault-tolerant program might want to fall back to backup procedures so
that meaningful results are returned to the application code, etc.  In
such cases, you should include your own version of @code{matherr} in
your program.

@code{matherr} is called with a single argument @var{exc} which is a
pointer to a structure defined on @code{<libm/math.h>} like this:

@example
struct exception @{
	int type;
	char *name;
	double arg1, arg2, retval;
@};
@end example

The member @code{type} is an integer code describing the type of
exception that has occurred.  It can be one of the following:

@table @code
@item DOMAIN
Argument(s) are outside the valid function domain (e.g.,
@code{log(-1)}).

@item SING
Argument(s) would result in a singularity (e.g., @code{log(0)}).

@item OVERFLOW
The result causes overflow, like in @code{exp(10000)}.

@item UNDERFLOW
The result causes underflow, like in @code{exp(-10000)}.

@item TLOSS
The result loses all significant digits, like in @code{sin(10e100)}.
@end table

These codes are defined on @code{<libm/math.h>}.

The member @code{name} points to the string that is the name of the
function which generated the exception.  The members @code{arg1} and
@code{arg2} are the values of the arguments with which the function was
called (@code{arg2} is undefined if the function only accepts a single
argument).  The member @code{retval} is set to the default value that
will be returned by the math library function; @code{matherr} can change
it to return a different value.

@subheading Return Value

@code{matherr} should return zero if it couldn't handle the exception,
or non-zero if the exception was handled.

If @code{matherr} returns zero, under @code{_SVID_} version an error
message is printed which includes the name of the function and the
exception type, and under @code{_SVID_} and @code{_XOPEN_} @code{errno}
is set to an appropriate value.  If @code{matherr} returns non-zero, no
error message is printed and @code{errno} is left unchanged.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  #include <libm/math.h>

  int matherr(register struct exception *x)
  @{
    switch (x->type) @{
      case DOMAIN:
        /* change sqrt to return sqrt(-arg1), not NaN */
        if (!strcmp(x->name, "sqrt")) @{
          x->retval = sqrt(-x->arg1);
          return 1; /* be silent: no message, don't set errno */
        @} /* FALL THROUGH */
      case SING:
        /* all other domain or sing exceptions,
         * print message and abort */
        fprintf(stderr, "domain exception in %s\n", x->name);
        abort();
        break;
    @}
    return 0; /* all other exceptions, execute default procedure */
  @}
@end example
@c -----------------------------------------------------------------------------
@node mblen, mbstowcs, matherr, Alphabetical List
@unnumberedsec mblen
@c From file ./ansi/locale/mblen.txh
@findex mblen
@subheading Syntax

@example
#include <stdlib.h>

int mblen(const char *s, size_t n);
@end example

@subheading Description

This function returns the number of characters of string @var{s} that
make up the next multibyte character.  No more than @var{n} characters
are checked.

If @var{s} is @code{NULL}, the internal shift state is reset.

@subheading Return Value

The number of characters that comprise the next multibyte character.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
int n = mblen(string, INT_MAX);
string += n;
@end example

@c -----------------------------------------------------------------------------
@node mbstowcs, mbtowc, mblen, Alphabetical List
@unnumberedsec mbstowcs
@c From file ./ansi/locale/mbstowcs.txh
@findex mbstowcs
@subheading Syntax

@example
#include <stdlib.h>

size_t mbstowcs(wchar_t *wcs, const char *s, size_t n);
@end example

@subheading Description

Converts a multibyte string to a wide character string.  The result
will be no more than @var{n} wide characters.

@subheading Return Value

The number of wide characters stored.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
int wlen = mbtowcs(wbuf, string, sizeof(wbuf)/sizeof(wchar_t));
@end example

@c -----------------------------------------------------------------------------
@node mbtowc, _media_type, mbstowcs, Alphabetical List
@unnumberedsec mbtowc
@c From file ./ansi/locale/mbtowc.txh
@findex mbtowc
@subheading Syntax

@example
#include <stdlib.h>

int mbtowc(wchar_t *pwc, const char *s, size_t n);
@end example

@subheading Description

Convert the first multibyte sequence in @var{s} to a wide character.
At most @var{n} characters are checked.  If @var{pwc} is not
@code{NULL}, the result is stored there.  If @var{s} is null, the
internal shift state is reset.

@subheading Return Value

The number of characters used by the multibyte sequence.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
string += mbtowc(&wc, string, strlen(string));
@end example

@c -----------------------------------------------------------------------------
@node _media_type, memalign, mbtowc, Alphabetical List
@unnumberedsec _media_type
@c From file ./dos/dos/mediatyp.txh
@findex _media_type
@subheading Syntax

@example
#include <dos.h>

int _media_type( const int drive );
@end example

@subheading Description

This function checks if drive number @var{drive} (1 == A:, 2 == B:,
etc., 0 == default drive) is fixed or removable.  

@code{_media_type} should only be called after you are sure the drive
isn't a CD-ROM or a RAM disk, since these might fool you with this
call.  

@subheading Return Value

1 if the drive is a fixed disk, 0 if it is removable. -1 on error.  

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

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

int main(void)
@{

  if( _media_type( 'C' - 'A' + 1 ) )
  @{
    printf("C: is (probably) a hard drive.\n");
  @}
  else
  @{
    printf("C: is (probably) a removable drive.\n");
  @}

  exit(0);
@}

@end example
@c -----------------------------------------------------------------------------
@node memalign, memccpy, _media_type, Alphabetical List
@unnumberedsec memalign
@c From file ./compat/stdlib/memalign.txh
@findex memalign
@subheading Syntax

@example
#include <malloc.h>

void *memalign(size_t alignment, size_t size);
@end example

@subheading Description

This function is like @code{malloc} (@pxref{malloc}) except the returned
pointer is a multiple of @var{alignment}. @var{alignment} must be a power of
2.

@subheading Return Value

A pointer to a newly allocated block of memory. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char *page = memalign(1024 * 4, 1024);
@end example
@c -----------------------------------------------------------------------------
@node memccpy, memchr, memalign, Alphabetical List
@unnumberedsec memccpy
@c From file ./compat/string/memccpy.txh
@findex memccpy
@subheading Syntax

@example
#include <string.h>

void * memccpy(void *to, const void *from, int ch, size_t nbytes)
@end example

@subheading Description

This function copies characters from memory area @var{from} into @var{to},
stopping after the first occurrence of character @var{ch} has been copied,
or after @var{nbytes} characters have been copied, whichever comes first.
The buffers should not overlap.

@subheading Return Value

A pointer to the character after the copy of @var{ch} in @var{to},
or a @code{NULL} pointer if @var{ch} was not found in the first
@var{nbytes} characters of @var{from}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char inpbuf[256], dest[81];

printf("Enter a path: ");
fflush(stdout);
gets(inpbuf);
memset(dest, 0, sizeof(dest));
if (memccpy(dest, inpbuf, '\\', 80))
  printf("The first directory in path is %s\n", dest);
else
  printf("No explicit directory in path\n");
@end example

@c -----------------------------------------------------------------------------
@node memchr, memcmp, memccpy, Alphabetical List
@unnumberedsec memchr
@c From file ./ansi/string/memchr.txh
@findex memchr
@subheading Syntax

@example
#include <string.h>

void *memchr(const void *string, int ch, size_t num);
@end example

@subheading Description

This function searches @var{num} bytes starting at @var{string}, looking
for the first occurrence of @var{ch}. 

@subheading Return Value

A pointer to the first match, or @code{NULL} if it wasn't found.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
if (memchr(path, '/', strlen(path))
  do_slash();
@end example

@c -----------------------------------------------------------------------------
@node memcmp, memcpy, memchr, Alphabetical List
@unnumberedsec memcmp
@c From file ./ansi/string/memcmp.txh
@findex memcmp
@subheading Syntax

@example
#include <string.h>

int memcmp(const void *s1, const void *s2, size_t num);
@end example

@subheading Description

This function compares two regions of memory, at @var{s1} and @var{s2},
for @var{num} bytes. 

@subheading Return Value

@table @asis

@item zero

s1 == s2

@item positive

s1 > s2

@item negative

s1 < s2

@end table


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node memcpy, memicmp, memcmp, Alphabetical List
@unnumberedsec memcpy
@c From file ./ansi/string/memcpy.txh
@findex memcpy
@subheading Syntax

@example
#include <string.h>

void *memcpy(void *dest, const void *src, int num);
@end example

@subheading Description

This function copies @var{num} bytes from @var{source} to @var{dest}.
It assumes that the source and destination regions don't overlap; if you
need to copy overlapping regions, use @code{memmove} instead.
@xref{memmove}.

@subheading Return Value

@var{dest}

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
memcpy(buffer, temp_buffer, BUF_MAX);
@end example

@c -----------------------------------------------------------------------------
@node memicmp, memmove, memcpy, Alphabetical List
@unnumberedsec memicmp
@c From file ./compat/string/memicmp.txh
@findex memicmp
@subheading Syntax

@example
#include <string.h>

int memicmp(const void *s1, const void *s2, size_t num);
@end example

@subheading Description

This function compares two regions of memory, at @var{s1} and @var{s2},
for @var{num} bytes, disregarding case.

@subheading Return Value

Zero if they're the same, nonzero if different, the sign indicates
"order". 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
if (memicmp(arg, "-i", 2) == 0)   /* '-I' or '-include' etc. */
  do_include();
@end example

@c -----------------------------------------------------------------------------
@node memmove, memset, memicmp, Alphabetical List
@unnumberedsec memmove
@c From file ./ansi/string/memmove.txh
@findex memmove
@subheading Syntax

@example
#include <string.h>

void *memmove(void *dest, const void *source, int num);
@end example

@subheading Description

This function copies @var{num} bytes from @var{source} to @var{dest}. 
The copy is done in such a way that if the two regions overlap, the
source is always read before that byte is changed by writing to the
destination. 

@subheading Return Value

@var{dest}

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
memmove(buf+1, buf, 99);
memmove(buf, buf+1, 99);
@end example

@c -----------------------------------------------------------------------------
@node memset, mkdir, memmove, Alphabetical List
@unnumberedsec memset
@c From file ./ansi/string/memset.txh
@findex memset
@subheading Syntax

@example
#include <string.h>

void *memset(void *buffer, int ch, size_t num);
@end example

@subheading Description

This function stores @var{num} copies of @var{ch}, starting at
@var{buffer}.  This is often used to initialize objects to a known
value, like zero.

Note that, although @var{ch} is declared @code{int} in the prototype,
@code{memset} only uses its least-significant byte to fill @var{buffer}.

@subheading Return Value

@var{buffer}

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
struct tm t;
memset(&t, 0, sizeof(t));
@end example

@c -----------------------------------------------------------------------------
@node mkdir, mkdtemp, memset, Alphabetical List
@unnumberedsec mkdir
@c From file ./posix/sys/stat/mkdir.txh
@findex mkdir
@subheading Syntax

@example
#include <sys/stat.h>

int mkdir(const char *path, mode_t mode);
@end example

@subheading Description

This function creates a subdirectory.

All the bits except @code{S_IWUSR} in the @var{mode} argument are
ignored under MS-DOS.  If @code{S_IWUSR} is @emph{not} set in
@var{mode}, the directory is created with read-only attribute bit set.
Note that DOS itself ignores the read-only bit of directories, but some
programs do not.

@subheading Return Value

Zero if the subdirectory was created, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
mkdir("/usr/tmp", S_IWUSR);
@end example

@c -----------------------------------------------------------------------------
@node mkdtemp, mkfifo, mkdir, Alphabetical List
@unnumberedsec mkdtemp
@c From file ./posix/stdlib/mkdtemp.txh
@findex mkdtemp
@subheading Syntax

@example
#include <stdlib.h>

char *mkdtemp(char *template);
@end example

@subheading Description

The @code{mkdtemp} function generates an uniquely named temporary directory
from template.  @var{template} is a file specification that ends with six
trailing @code{X} characters.  This function replaces the @code{XXXXXX} with
a set of characters such that the resulting directory name names a nonexistant
directory.  It then creates the directory.

Note that since MS-DOS and file systems that lack of @acronym{LFN} support
are limited to eight characters for the file name, and since none of the @code{X}'s
get replaced by a dot, you can only have two additional characters before
the @code{X}'s.  But if the file systems offers @acronym{LFN} support no limitation
concerning the number of characters before the @code{X}'s is given and the
created file names will be @acronym{POSIX} compliant.

Note also that the path you give will be modified in place.

@subheading Return Value

The pointer to the modified template string on success,
and @code{NULL} on failure, in which case @code{errno} is set
appropriately.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
char temp_dir, path[100];
strcpy(path, _USE_LFN ? "/tmp/temp_directoryXXXXXX" : "/tmp/tdXXXXXX");
temp_dir = mkdtemp(path);
@end example
@c -----------------------------------------------------------------------------
@node mkfifo, mknod, mkdtemp, Alphabetical List
@unnumberedsec mkfifo
@c From file ./posix/sys/stat/mkfifo.txh
@findex mkfifo
@subheading Syntax

@example
#include <sys/stat.h>

int mkfifo(const char *path, mode_t mode);
@end example

@subheading Description

This function is provided only to assist in porting from Unix.  It
always returns an error condition. 


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node mknod, mkstemp, mkfifo, Alphabetical List
@unnumberedsec mknod
@c From file ./compat/sys/stat/mknod.txh
@findex mknod
@subheading Syntax

@example
#include <sys/stat.h>

int mknod(const char *path, mode_t mode, dev_t dev);
@end example

@subheading Description

This function is provided to assist in porting from Unix.  If @var{mode}
specifies a regular file, @code{mknod} creates a file using @var{path}
as its name.  If @var{mode} specifies a character device, and if the
device whose name is given by @var{path} exists and its device
specification as returned by @code{stat} or @code{fstat} is equal to
@var{dev}, @code{mknod} returns -1 and sets @code{errno} to
@code{EEXIST}.  In all other cases, -1 is returned @code{errno} is set
to @code{EACCES}.

The argument @var{dev} is ignored if @var{mode} does not specify a
character device.

@subheading Return Value

Zero on success, -1 on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable

@c -----------------------------------------------------------------------------
@node mkstemp, mktemp, mknod, Alphabetical List
@unnumberedsec mkstemp
@c From file ./compat/stdio/mkstemp.txh
@findex mkstemp
@subheading Syntax

@example
#include <stdlib.h>

int mkstemp(char *template);
@end example

@subheading Description

@var{template} is a file specification that ends with six trailing
@code{X} characters.  This function replaces the @code{XXXXXX} with a
set of characters such that the resulting file name names a nonexistant
file.  It then creates and opens the file in a way which guarantees that
no other process can access this file.

Note that since MS-DOS and file systems that lack of @acronym{LFN} support
are limited to eight characters for the file name, and since none of the @code{X}'s
get replaced by a dot, you can only have two additional characters before
the @code{X}'s.  But if the file systems offers @acronym{LFN} support no limitation
concerning the number of characters before the @code{X}'s is given and the
created file names will be @acronym{POSIX} compliant.

Note also that the path you give will be modified in place.

@subheading Return Value

The open file descriptor.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
To follow the Single Unix Specification, djgpp 2.04 has now
the prototype in @code{<stdlib.h>}.  To keep backward compatibility, the
prototype is also kept in @code{<stdio.h>} but its usage is deprecated.

@end enumerate

@subheading Example

@example
char path[100];
strcpy(path, _USE_LFN ? "/tmp/c_compilerXXXXXX" : "/tmp/ccXXXXXX");
int fd = mkstemp(path);
@end example

@c -----------------------------------------------------------------------------
@node mktemp, mktime, mkstemp, Alphabetical List
@unnumberedsec mktemp
@c From file ./compat/stdio/mktemp.txh
@findex mktemp
@subheading Syntax

@example
#include <stdlib.h>

char *mktemp(char *template);
@end example

@subheading Description

@var{template} is a file specification that ends with six trailing
@code{X} characters.  This function replaces the @code{XXXXXX} with a
set of characters such that the resulting file name names a nonexisting
file.

Note that since MS-DOS and file systems that lack of @acronym{LFN} support
are limited to eight characters for the file name, and since none of the @code{X}'s
get replaced by a dot, you can only have two additional characters before
the @code{X}'s.  But if the file systems offers @acronym{LFN} support no limitation
concerning the number of characters before the @code{X}'s is given and the
created file names will be @acronym{POSIX} compliant.

@subheading Return Value

If a unique name cannot be chosen, @code{NULL} is returned.  Otherwise
the resulting filename is returned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
To follow the Single Unix Specification, djgpp 2.04 has now
the prototype in @code{<stdlib.h>}.  To keep backward compatibility, the
prototype is also kept in @code{<stdio.h>} but its usage is deprecated.

@end enumerate

@subheading Example

@example
char template[] = _USE_LFN ? "/tmp/c_compilerXXXXXX" : "/tmp/ccXXXXXX";
if (mktemp(template) != NULL)
  @{
    FILE *q = fopen(template, "w");
    @dots{}
  @}
@end example

@c -----------------------------------------------------------------------------
@node mktime, modf, mktemp, Alphabetical List
@unnumberedsec mktime
@c From file ./ansi/time/ctime.txh
@findex mktime
@vindex TZ@r{ environment variable, and time since 1970}
@subheading Syntax

@example
#include <time.h>

time_t mktime(struct tm *tptr);
@end example

@subheading Description

This function converts a time structure into the number of seconds since
00:00:00 GMT 1/1/1970.  It also attempts to normalize the fields of
@var{tptr}.  The layout of a @code{struct tm} is as follows:

@example
struct tm @{
  int    tm_sec;    /* seconds after the minute [0-60] */
  int    tm_min;    /* minutes after the hour [0-59] */
  int    tm_hour;   /* hours since 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 */
  long   tm_gmtoff; /* offset from GMT in seconds */
  char * tm_zone;   /* timezone abbreviation */
@};
@end example

If you don't know whether daylight saving is in effect at the moment
specified by the contents of @var{tptr}, set the @code{tm_isdst} member
to -1, which will cause @code{mktime} to compute the DST flag using the
data base in the @file{zoneinfo} subdirectory of your main DJGPP
installation.  This requires that you set the environment variable
@code{TZ} to a file in that directory which corresponds to your
geographical area.

@subheading Return Value

The resulting time, or -1 if the time in @var{tptr} cannot be described
in that format. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node modf, modfl, mktime, Alphabetical List
@unnumberedsec modf
@c From file ./ansi/math/modf.txh
@findex modf
@subheading Syntax

@example
#include <math.h>

double modf(double x, double *pint);
@end example

@subheading Description

@code{modf} breaks down @var{x} into its integer portion (which it
stores in @var{*pint}) and the remaining fractional portion, which it
returns.  Both integer and fractional portions have the same sign as
@var{x}, except if @var{x} is a negative zero, in which case the integer
part is a positive zero.

@subheading Return Value

The fractional portion.  If @var{x} is @code{Inf} or @code{NaN}, the
return value is zero, the integer portion stored in @var{*pint} is the
same as the value of @var{x}, and @code{errno} is set to @code{EDOM}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node modfl, moncontrol, modf, Alphabetical List
@unnumberedsec modfl
@c From file ./ansi/math/modfl.txh
@findex modfl
@subheading Syntax

@example
#include <math.h>

long double modfl(long double x, long double *pint);
@end example

@subheading Description

@code{modfl} breaks down @var{x} into its integer portion (which it
stores in @var{*pint}) and the remaining fractional portion, which it
returns.

@subheading Return Value

The fractional portion.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node moncontrol, _mono_clear, modfl, Alphabetical List
@unnumberedsec moncontrol
@c From file ./crt0/mcount.txh
@findex moncontrol
@subheading Syntax

@example
#include <sys/gmon.h>

int moncontrol (int mode);
@end example

@subheading Description

This function allows to control collection of profiling information
during the program run.  Profiling begins when a program linked with the
@samp{-pg} option starts, or when @code{monstartup} is called
(@pxref{monstartup}).  To stop the collection of histogram ticks and
function call counts, call @code{moncontrol} with a zero argument
@var{mode}; this stops the timer used to sample the program counter
(@code{EIP}) values and disables the code which counts how many times
each function compiled with @samp{-pg} was called.  To resume collection
of profile data, call @code{moncontrol} with a non-zero argument.

Note that the profiling output is always written to the file
@file{gmon.out} at program exit time, regardless of whether profiling is
on or off.

@subheading Return Value

@code{moncontrol} returns the previous state of profiling: zero if it
was turned off, non-zero if it was on.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
 extern void my_func();
 extern void my_func_end();
 /* Profile only one function.  */
 monstartup((unsigned long)my_func, (unsigned long)my_func_end);
 ...
 /* Stop profiling.  */
 moncontrol(0);
 ...
 /* Resume profiling.  */
 moncontrol(1);
@end example
@c -----------------------------------------------------------------------------
@node _mono_clear, _mono_printf, moncontrol, Alphabetical List
@unnumberedsec _mono_clear
@c From file ./pc_hw/mono/mono.txh
@findex _mono_clear
@subheading Syntax

@example
#include <sys/mono.h>

void _mono_clear(void);
@end example

@subheading Description

Clears the monochrome monitor.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _mono_printf, _mono_putc, _mono_clear, Alphabetical List
@unnumberedsec _mono_printf
@c From file ./pc_hw/mono/mono.txh
@findex _mono_printf
@subheading Syntax

@example
#include <sys/mono.h>

void _mono_printf(const char *fmt, ...);
@end example

@subheading Description

Like @ref{printf}, but prints to the monochrome monitor.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _mono_putc, monstartup, _mono_printf, Alphabetical List
@unnumberedsec _mono_putc
@c From file ./pc_hw/mono/mono.txh
@findex _mono_putc
@subheading Syntax

@example
#include <sys/mono.h>

void _mono_putc(int c);
@end example

@subheading Description

Prints a single character to the monochrome monitor.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node monstartup, movedata, _mono_putc, Alphabetical List
@unnumberedsec monstartup
@c From file ./crt0/mcount.txh
@findex monstartup
@subheading Syntax

@example
#include <sys/gmon.h>

int monstartup (unsigned long lowpc, unsigned long highpc);
@end example

@subheading Description

This function allows to selectively collect profiling information for a
specific range of addresses.  The arguments specify the address range
that is to be sampled: the lowest address is given by @var{lowpc} and
the highest is just below @var{highpc}.  @code{monstartup} arranges for
the profiling data to be gathered and written at program exit time, and
then calls the @code{moncontrol} function (@pxref{moncontrol}) to start
profiling.

The call graph printed by the
@code{gprof} utility will only include functions in this range compiled
with the @samp{-pg} option, but @code{EIP} sampling triggered by the
timer tick will measure execution time of all the functions in the
specified range.

This function should be called by a program which was not linked with
the @samp{-pg} linker switch.  If @samp{-pg} @emph{was} used during
linking, @code{monstartup} is called automatically by the startup code
with arguments which span the entire range of executable addresses in
the program, from the program's entry point to the highest code segment
address.

Only the first call to this function has an effect; any further calls
will do nothing and return a failure indication.  (In particular, in a
program linked with @samp{-pg}, this function always fails, since the
startup code already called it.)  This is because @code{monstartup} sets
up some internal data structures which cannot be resized if a different
address range is requested.

Profiling begins on return from this function.  You can use
@code{moncontrol} (@pxref{moncontrol}) to turn profiling off and on.

@subheading Return Value

Zero on success, non-zero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@xref{moncontrol}.

@c -----------------------------------------------------------------------------
@node movedata, movedatab, monstartup, Alphabetical List
@unnumberedsec movedata
@c From file ./pc_hw/mem/md.txh
@findex movedata
@subheading Syntax

@example
#include <sys/movedata.h>

void movedata(unsigned source_selector, unsigned source_offset,
              unsigned dest_selector, unsigned dest_offset,
              size_t length);
@end example

@subheading Description

This function allows the caller to directly transfer information
between conventional and linear memory, and among each as well.  The
selectors passed are @emph{not} segment values like in DOS.  They are
protected mode selectors that can be obtained by the @code{_my_ds} and
@code{_go32_info_block.selector_for_linear_memory} (or just
@code{_dos_ds}, which is defined in the include file go32.h) functions
(@ref{_my_ds}, @pxref{_go32_info_block}).
The offsets are linear offsets.  If the selector is for the program's
data area, this offset corresponds to the address of a buffer (like
@code{(unsigned)&something}).  If the selector is for the conventional
memory area, the offset is the physical address of the memory, which
can be computed from a traditional segment/offset pair as
@code{segment}*16+@code{offset}.  For example, the color text screen
buffer is at offset 0xb8000.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
short blank_row_buf[ScreenCols()];
/* scroll screen */
movedata(_dos_ds, 0xb8000 + ScreenCols()*2,
         _dos_ds, 0xb8000,
         ScreenCols() * (ScreenRows()-1) * 2);
/* fill last row */
movedata(_my_ds(), (unsigned)blank_row_buf,
         _dos_ds, 0xb8000 + ScreenCols()*(ScreenRows()-1)*2,
          ScreenCols() * 2);
@end example
@c -----------------------------------------------------------------------------
@node movedatab, movedatal, movedata, Alphabetical List
@unnumberedsec movedatab
@c From file ./pc_hw/mem/mdb.txh
@findex _movedatab
@subheading Syntax

@example
#include <sys/movedata.h>

void _movedatab(unsigned, unsigned, unsigned, unsigned, size_t);
@end example

@subheading Description

Just like @ref{movedata}, but all transfers are always 8-bit
transfers.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node movedatal, movedataw, movedatab, Alphabetical List
@unnumberedsec movedatal
@c From file ./pc_hw/mem/mdl.txh
@findex _movedatal
@subheading Syntax

@example
#include <sys/movedata.h>

void _movedatal(unsigned, unsigned, unsigned, unsigned, size_t);
@end example

@subheading Description

Just like @ref{movedata}, but all transfers are always 32-bit
transfers, and the count is a count of transfers, not bytes.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node movedataw, movetext, movedatal, Alphabetical List
@unnumberedsec movedataw
@c From file ./pc_hw/mem/mdw.txh
@findex _movedataw
@subheading Syntax

@example
#include <sys/movedata.h>

void _movedataw(unsigned, unsigned, unsigned, unsigned, size_t);
@end example

@subheading Description

Just like @ref{movedata}, but all transfers are always 16-bit
transfers, and the count is a count of transfers, not bytes.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node movetext, mprotect, movedataw, Alphabetical List
@unnumberedsec movetext
@c From file ./pc_hw/co80/conio.txh
@findex movetext
@subheading Syntax

@example
#include <conio.h>

int movetext(int _left, int _top, int _right, int _bottom, 
             int _destleft, int _desttop);
@end example

@subheading Description

Moves a block of text on the screen.

@subheading Return Value

1 on success, zero on error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node mprotect, _my_cs, movetext, Alphabetical List
@unnumberedsec mprotect
@c From file ./compat/mman/mprotect.txh
@findex mprotect
@subheading Syntax

@example
#include <sys/types.h>
#include <sys/mman.h>

int mprotect(void *addr, size_t len, int prot);
@end example

@subheading Description

This function modifies the access protection of a memory region.  Protection
occurs in 4Kbyte regions (pages) aligned on 4Kbyte boundaries.  All pages 
in the region will be changed, so @var{addr} and @var{len} should be multiples 
of 4096.

The protection @var{prot} for each page is specified with the values:
  PROT_NONE  Region can not be touched (if or'ed is ignored).
  PROT_READ  Region can be read (can be or'ed with PROT_WRITE).
  PROT_WRITE Region can be written (implies read access).
  
This function is only supported on DPMI hosts which provide some V1.0 extensions
on V0.9 memory blocks.

@subheading Return Value

The function returns 0 if successful and the value -1 if all the pages 
could not be set.  

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
mprotect(readonly_buffer,8192,PROT_READ);
mprotect(guard_area,4096,PROT_NONE);
mprotect(NULL,4096,PROT_WRITE); /* Let NULL pointers not generate
                                 * exceptions */
@end example

@c -----------------------------------------------------------------------------
@node _my_cs, _my_ds, mprotect, Alphabetical List
@unnumberedsec _my_cs
@c From file ./pc_hw/cpu/my_cs.txh
@findex _my_cs
@subheading Syntax

@example
#include <sys/segments.h>

unsigned short _my_cs();
@end example

@subheading Description

Returns the current @code{CS}.  This is useful for setting up interrupt
vectors and such. 

@subheading Return Value

@code{CS}


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _my_ds, _my_ss, _my_cs, Alphabetical List
@unnumberedsec _my_ds
@c From file ./pc_hw/cpu/my_ds.txh
@findex _my_ds
@subheading Syntax

@example
#include <sys/segments.h>

unsigned short _my_ds();
@end example

@subheading Description

Returns the current @code{DS}.  This is useful for setting up interrupt
vectors and such. 

@subheading Return Value

@code{DS}


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _my_ss, nan, _my_ds, Alphabetical List
@unnumberedsec _my_ss
@c From file ./pc_hw/cpu/my_ss.txh
@findex _my_ss
@subheading Syntax

@example
#include <sys/segments.h>

unsigned short _my_ss();
@end example

@subheading Description

Returns the current @code{SS}.  This is useful for setting up interrupt
vectors and such. 

@subheading Return Value

@code{SS}


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node nan, nanf, _my_ss, Alphabetical List
@unnumberedsec nan
@c From file ./c99/math/nan.txh
@findex nan
@subheading Syntax

@example
#include <math.h>

double nan(const char *tagp);
@end example

@subheading Description

@code{nan} returns a quiet NaN with contents indicated by @var{tagp}.

@subheading Return Value

The quiet NaN.

If quiet NaNs are not supported, zero is returned. DJGPP supports
quiet NaNs.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@end multitable


@subheading Example

@example
double d = nan("0x1234");
@end example
@c -----------------------------------------------------------------------------
@node nanf, nanl, nan, Alphabetical List
@unnumberedsec nanf
@c From file ./c99/math/nanf.txh
@findex nanf
@subheading Syntax

@example
#include <math.h>

float nanf(const char *tagp);
@end example

@subheading Description

@code{nanf} returns a quiet NaN with contents indicated by @var{tagp}.

@subheading Return Value

The quiet NaN.

If quiet NaNs are not supported, zero is returned. DJGPP supports
quiet NaNs.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@end multitable


@subheading Example

@example
float f = nanf("0x1234");
@end example
@c -----------------------------------------------------------------------------
@node nanl, nice, nanf, Alphabetical List
@unnumberedsec nanl
@c From file ./c99/math/nanl.txh
@findex nanl
@subheading Syntax

@example
#include <math.h>

long double nanl(const char *tagp);
@end example

@subheading Description

@code{nanl} returns a quiet NaN with contents indicated by @var{tagp}.

@subheading Return Value

The quiet NaN.

If quiet NaNs are not supported, zero is returned. DJGPP supports
quiet NaNs.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@end multitable


@subheading Example

@example
long double ld = nanl("0x1234");
@end example
@c -----------------------------------------------------------------------------
@node nice, normvideo, nanl, Alphabetical List
@unnumberedsec nice
@c From file ./compat/unistd/nice.txh
@findex nice
@subheading Syntax

@example
#include <unistd.h>

int nice(int _increment);
@end example

@subheading Description

Adjusts the priority of the process.  Provided for Unix compatibility
only.

@subheading Return Value

The new nice value.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node normvideo, nosound, nice, Alphabetical List
@unnumberedsec normvideo
@c From file ./pc_hw/co80/conio.txh
@findex normvideo
@subheading Syntax

@example
#include <conio.h>

void normvideo(void);
@end example

@subheading Description

Resets the text attribute to what it was before the program started.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node nosound, ntohl, normvideo, Alphabetical List
@unnumberedsec nosound
@c From file ./pc_hw/sound/sound.txh
@findex nosound
@subheading Syntax

@example
#include <pc.h>

void nosound(void);
@end example

@subheading Description

Disable the PC speaker.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node ntohl, ntohs, nosound, Alphabetical List
@unnumberedsec ntohl
@c From file ./pc_hw/endian/ntohl.txh
@findex ntohl
@subheading Syntax

@example
#include <netinet/in.h>

unsigned long ntohl(unsigned long val);
@end example

@subheading Description

This function converts from network formatted longs to host formatted
longs.  For the i386 and higher processors, this means that the bytes
are swapped from 1234 order to 4321 order.

@subheading Return Value

The host-order value.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
ip = ntohl(packet.ipaddr);
@end example

@c -----------------------------------------------------------------------------
@node ntohs, open, ntohl, Alphabetical List
@unnumberedsec ntohs
@c From file ./pc_hw/endian/ntohs.txh
@findex ntohs
@subheading Syntax

@example
#include <netinet/in.h>

unsigned short ntohs(unsigned short val);
@end example

@subheading Description

This function converts from network formatted shorts to host formatted
shorts.  For the i386 and higher processors, this means that the bytes
are swapped from 12 order to 21 order.

@subheading Return Value

The host-order value.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
port = ntohs(tcp.port);
@end example

@c -----------------------------------------------------------------------------
@node open, _open, ntohs, Alphabetical List
@unnumberedsec open
@c From file ./posix/fcntl/open.txh
@findex open
@subheading Syntax

@example
#include <fcntl.h>    /* provides mode definitions */
#include <sys/stat.h> /* provides permission definitions */

int open(const char *file, int mode /*, int permissions */);
@end example

@subheading Description

This function opens the named @var{file} in the given @var{mode}, which
is any combination of the following bits:

@table @code

@item O_RDONLY

The file is opened for reading.

@item O_WRONLY

The file is opened for writing.

@item O_RDWR

The file is opened for both reading and writing.

@item O_CREAT

If the file does not exist, it is created. @xref{creat}.

@item O_TRUNC

If the file does exist, it is truncated to zero bytes.

@item O_EXCL

If the file exists, and @code{O_CREAT} is also specified, the
@code{open} call will fail.  If the file is a symlink and @code{O_CREAT}
is also specified, then the contents of the symlink are ignored -
the @code{open} call will fail.

@item O_APPEND

The file pointer is positioned at the end of the file before each write. 

@item O_TEXT

The file is opened in text mode, meaning that Ctrl-M characters are
stripped on reading and added on writing as needed.  The default mode is
specified by the @code{_fmode} variable @ref{_fmode}. 

@item O_BINARY

The file is opened in binary mode.

When called to open the console in binary mode, @code{open} will disable
the generation of @code{SIGINT} when you press @kbd{Ctrl-C}
(@kbd{Ctrl-Break} will still cause @code{SIGINT}), because many programs
that use binary reads from the console will also want to get the
@samp{^C} characters.  You can use the @code{__djgpp_set_ctrl_c} library
function (@pxref{__djgpp_set_ctrl_c}) if you want @kbd{Ctrl-C} to
generate interrupts while console is read in binary mode.

@item O_NOINHERIT

Child processes will not inherit this file handle.  This is also known
as @dfn{close-on-exec}--see @ref{fcntl}.  This bit is DOS- and
Windows-specific; portable programs should use @code{fcntl} instead.

@item O_NOFOLLOW

@code{open} will fail with @code{errno} set to @code{ELOOP}, if the last path 
component in @var{file} is symlink.

@item O_NOLINK

If @var{file} is a symlink, @code{open} will open symlink file itself instead 
of referred file.

@item O_TEMPORARY

Delete @var{file} when all file descriptors that refer to it are closed.

Note that @var{file} should not also be opened with the low-level functions
@code{_creat}, @code{_creatnew}, @code{_dos_creat}, @code{_dos_creatnew},
and @code{_dos_open}.  Otherwise @var{file} may not be deleted as expected.

@end table

If the file is created by this call, it will be given the read/write
permissions specified by @var{permissions}, which may be any combination
of these values:

@table @code

@item S_IRUSR

The file is readable.  This is always true for MS-DOS.

@item S_IWUSR

The file is writable.

@end table

Other @code{S_I*} values may be included, but they will be ignored.

You can specify the share flags (a DOS specific feature) in @var{mode}.
And you can indicate default values for the share flags in
@code{__djgpp_share_flags}. @xref{__djgpp_share_flags}.

You can open directories using @code{open}, but there is limited
support for POSIX file operations on directories.  In particular,
directories cannot be read using @code{read} (@pxref{read})
or written using @code{write} (@pxref{write}).  The principal reason
for allowing @code{open} to open directories is to support changing
directories using @code{fchdir} (@pxref{fchdir}).  If you wish to read
the contents of a directory, use the @code{opendir} (@pxref{opendir})
and @code{readdir} (@pxref{readdir}) functions instead.  File descriptors
for directories are not inherited by child programs.

@subheading Return Value

If successful, the file descriptor is returned.  On error, a negative
number is returned and @code{errno} is set to indicate the error. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
int q = open("/tmp/foo.dat", O_RDONLY|O_BINARY);
@end example

@c -----------------------------------------------------------------------------
@node _open, opendir, open, Alphabetical List
@unnumberedsec _open
@c From file ./dos/io/_open.txh
@findex _open
@subheading Syntax

@example
#include <io.h>

int _open(const char *path, int attrib);
@end example

@subheading Description

This is a direct connection to the MS-DOS open function call, int 0x21,
%ah = 0x3d, on versions of DOS earlier than 7.0. On DOS version 7.0 or
later @code{_open} calls function int 0x21, %ax = 0x6c00. When long
file names are supported, @code{_open} calls function 0x716c of Int
0x21.

On FAT32 file systems file sizes up to 2^32-2 are supported. Note
that WINDOWS 98 has a bug which only lets you create these big files
if LFN is enabled. In plain DOS mode it plainly works.

The file is set to binary mode.

The @var{attrib} parameter is a combination of one or more bits from the
following:

@table @code
@item O_RDONLY
open for read only

@item O_WRONLY
open for write only

@item O_RDWR
open for read and write

@item O_NOINHERIT
file handle is not inherited by child processes

@item SH_COMPAT
open in compatibility mode

@item SH_DENYRW
deny requests by other processes to open the file for eaither reading or
writing

@item SH_DENYWR
deny requests to open the file for writing

@item SH_DENYRD
deny requests to open the file for reading

@item SH_DENYNO
deny-none mode: allow other processes to open the file if their open
mode doesn't conflict with the open mode of this process
@end table

This function can be hooked by File System Extensions
(@pxref{File System Extensions}).  If you don't want this, you should
use @code{_dos_open} (@pxref{_dos_open}) (but note that the latter
doesn't support long file names).

@subheading Return Value

The new file descriptor, else -1 on error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable

@c -----------------------------------------------------------------------------
@node opendir, outb, _open, Alphabetical List
@unnumberedsec opendir
@c From file ./posix/dirent/opendir.txh
@findex opendir
@subheading Syntax

@example
#include <dirent.h>

extern int __opendir_flags;

DIR *opendir(char *name);
@end example

@subheading Description

This function "opens" a directory so that you can read the list of file
names in it.  The pointer returned must be passed to @code{closedir}
when you are done with it.  @xref{readdir}.

The global variable @code{__opendir_flags} can be set to include the
following values to control the operation of @code{opendir}:

@table @code

@item __OPENDIR_PRESERVE_CASE
Do not change the case of files to lower case.  Just in case Micros*ft
decides to support case-sensitive file systems some day.

You can also use this flag if you want the names of files like
@file{README} and @file{FAQ} from Unix distributions to be returned in
upper-case on Windows 9X filesystems.  @xref{_preserve_fncase}, for
other ways of achieving this and for more detailed description of the
automatic letter-case conversion by DJGPP library functions.

@item __OPENDIR_NO_HIDDEN
Do not include hidden files and directories in the search.  By default,
all files and directories are included.

@item __OPENDIR_FIND_HIDDEN
Provided for back-compatibility with previous DJGPP versions, where
hidden files and directories were by default skipped.  In versions 2.02
and later, this flag has no effect.

@item __OPENDIR_FIND_LABEL
Include volume labels in the search.  By default, these are skipped.

@item __OPENDIR_NO_D_TYPE
Do not compute the @code{d_type} member of @code{struct dirent}.  If
this flag is set, all files will get @code{DT_UNKNOWN} in the
@code{d_type} member.  By default, this flag is reset.  @xref{readdir}.
@end table

You can simply put @samp{int __opendir_flags = ...;} in your code.  The
default is to let it get set to zero as an uninitialized variable.

@subheading Return Value

The open directory structure, or @code{NULL} on error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
The @code{__opendir_flags} variable is DJGPP-specific.
@end enumerate

@subheading Example

@example
DIR *d = opendir(".");
closedir(d);
@end example

@c -----------------------------------------------------------------------------
@node outb, outp, opendir, Alphabetical List
@unnumberedsec outb
@c From file ./pc_hw/io/outb.txh
@findex outb
@subheading Syntax

@example
#include <pc.h>

void outb(unsigned short _port, unsigned char _data);
@end example

@subheading Description

Calls @ref{outportb}. Provided only for compatibility.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node outp, outportb, outb, Alphabetical List
@unnumberedsec outp
@c From file ./pc_hw/io/outp.txh
@findex outp
@subheading Syntax

@example
#include <pc.h>

void outp(unsigned short _port, unsigned char  _data);
@end example

@subheading Description

Calls @ref{outportb}. Provided only for compatibility.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node outportb, outportl, outp, Alphabetical List
@unnumberedsec outportb
@c From file ./pc_hw/io/ob.txh
@findex outportb
@subheading Syntax

@example
#include <pc.h>

void outportb(unsigned short _port, unsigned char  _data);
@end example

@subheading Description

Write a single byte to an 8-bit port.

This function is provided as an inline assembler macro, and will be
optimized down to a single opcode when you optimize your program.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node outportl, outportsb, outportb, Alphabetical List
@unnumberedsec outportl
@c From file ./pc_hw/io/ol.txh
@findex outportl
@subheading Syntax

@example
#include <pc.h>

void outportl(unsigned short _port, unsigned long _data);
@end example

@subheading Description

Write a single long to an 32-bit port.

This function is provided as an inline assembler macro, and will be
optimized down to a single opcode when you optimize your program.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node outportsb, outportsl, outportl, Alphabetical List
@unnumberedsec outportsb
@c From file ./pc_hw/io/osb.txh
@findex outportsb
@subheading Syntax

@example
#include <pc.h>

void outportsb(unsigned short _port,
               const unsigned char *_buf, unsigned _len);
@end example

@subheading Description

Writes the @var{_len} bytes in @var{_buf} to the 8-bit @var{_port}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node outportsl, outportsw, outportsb, Alphabetical List
@unnumberedsec outportsl
@c From file ./pc_hw/io/osl.txh
@findex outportsl
@subheading Syntax

@example
#include <pc.h>

void outportsl(unsigned short _port,
               const unsigned long *_buf, unsigned _len);
@end example

@subheading Description

Writes the @var{_len} longs in @var{_buf} to the 32-bit @var{_port}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node outportsw, outportw, outportsl, Alphabetical List
@unnumberedsec outportsw
@c From file ./pc_hw/io/osw.txh
@findex outportsw
@subheading Syntax

@example
#include <pc.h>

void outportsw(unsigned short _port,
               const unsigned short *_buf, unsigned _len);
@end example

@subheading Description

Writes the @var{_len} shorts in @var{_buf} to the 16-bit @var{_port}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node outportw, outpw, outportsw, Alphabetical List
@unnumberedsec outportw
@c From file ./pc_hw/io/ow.txh
@findex outportw
@subheading Syntax

@example
#include <pc.h>

void outportw(unsigned short _port, unsigned short _data);
@end example

@subheading Description

Write a single short to an 16-bit port.

This function is provided as an inline assembler macro, and will be
optimized down to a single opcode when you optimize your program.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node outpw, pathconf, outportw, Alphabetical List
@unnumberedsec outpw
@c From file ./pc_hw/io/outpw.txh
@findex outpw
@subheading Syntax

@example
#include <pc.h>

void outpw(unsigned short _port, unsigned short _data);
@end example

@subheading Description

Calls @ref{outportw}. Provided only for compatibility.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node pathconf, pause, outpw, Alphabetical List
@unnumberedsec pathconf
@c From file ./posix/unistd/pathconf.txh
@findex pathconf
@subheading Syntax

@example
#include <unistd.h>

long pathconf(const char *filename, int name);
@end example

@subheading Description

This function returns various system-dependent configuration values. 
The @var{name} is one of the following:

@table @code

@item _PC_LINK_MAX

The maximum number of directory entries that can refer to a single real
file.  Always 1 in DJGPP.

@item _PC_MAX_CANON

The maximum number of bytes in an editable input line.  In DJGPP, this
is 126 (DOS restriction).

@item _PC_MAX_INPUT

The maximum number of bytes in a non-editable input line.  Also 126 in
DJGPP.

@item _PC_NAME_MAX

The maximum length of an individual file name.  If the filesystem where
@var{filename} resides supports long file names, the result is whatever
@code{_get_volume_info} returns (usually 255); otherwise 12 will be
returned.  @xref{_use_lfn}.

@item _PC_PATH_MAX

The maximum length of a complete path name.  If the filesystem where
@var{filename} resides supports long file names, the result is whatever
@code{_get_volume_info} returns (usually 260); otherwise 80 will be
returned.  @xref{_use_lfn}.

@item _PC_PIPE_BUF

The size of a pipe's internal buffer.  In DJGPP, this returns 512.

@item _PC_CHOWN_RESTRICTED

If non-zero, only privileged user can change the ownership of files by
calling @code{chown}, otherwise anyone may give away files.  The DJGPP
version always returns zero, since MS-DOS files can be freely given
away.

@item _PC_NO_TRUNC

If zero is returned, filenames longer than what 
@w{@code{pathconf (filename, _PC_NAME_MAX)}} returns are truncated,
otherwise an error occurs if you use longer names.  In DJGPP, this
returns 0, since DOS always silently truncates long names.

@item _PC_VDISABLE

A character to use to disable tty special characters.  DJGPP currently
doesn't support special characters, so this returns -1.

@end table

@subheading Return Value

The selected configuration value is returned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
char *buf = malloc(pathconf("c:/", _PC_MAX_PATH)+1);
@end example

@c -----------------------------------------------------------------------------
@node pause, pclose, pathconf, Alphabetical List
@unnumberedsec pause
@c From file ./posix/unistd/pause.txh
@findex pause
@subheading Syntax

@example
#include <unistd.h>

int pause(void);
@end example

@subheading Description

This function just calls @code{__dpmi_yield()} (@pxref{__dpmi_yield})
to give up a slice of the CPU.

@subheading Return Value

Zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node pclose, perror, pause, Alphabetical List
@unnumberedsec pclose
@c From file ./posix/stdio/popen.txh
@findex pclose
@subheading Syntax

@example
#include <stdio.h>

int pclose(FILE *pipe);
@end example

@subheading Description

This function closes a pipe opened with @code{popen} (@pxref{popen}). 
Note that since MS-DOS is not multitasking, this function will actually
run the program specified in @code{popen} if the pipe was opened for
writing. 

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
FILE *f = popen("sort", "w");
write_to_pipe(f);
pclose(f);
@end example

@c -----------------------------------------------------------------------------
@node perror, pipe, pclose, Alphabetical List
@unnumberedsec perror
@c From file ./ansi/stdio/perror.txh
@findex perror
@subheading Syntax

@example
#include <stdio.h>

void perror(const char *string);
@end example

@subheading Description

This function formats an error message and prints it to @code{stderr}. 
The message is the @var{string}, a colon and a blank, and a message
suitable for the error condition indicated by @code{errno}. 
If @var{string} is a null pointer or points to a null string,
the colon and blank are not printed.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
int x = open("foo", O_RDONLY);
if (x < 0)
@{
  perror("foo");
  exit(1);
@}
@end example

@c -----------------------------------------------------------------------------
@node pipe, popen, perror, Alphabetical List
@unnumberedsec pipe
@c From file ./posix/unistd/pipe.txh
@findex pipe
@subheading Syntax

@example
#include <unistd.h>

int pipe(int fildes[2]);
@end example

@subheading Description

This function creates a pipe and places a file descriptor for the read end
of the pipe in @code{@var{fildes}[0]}, and another for the write end in
@code{@var{fildes}[1]}.  Data written to @code{@var{fildes}[1]} will be read
from @code{@var{fildes}[0]} on a first-in first-out (FIFO) basis.

Note this pipe implementation won't help port instances of
@code{fork}/@code{exec} or any other methods that require support for
multitasking.

@subheading Return Value

Zero for success, otherwise -1 is returned and @code{errno} is set to indicate
the error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example

#include <unistd.h>
#include <process.h>

/* Pipe the output of program to the input of another. */

int main()
@{
  int pipe_fds[2];
  int stdin_save, stdout_save;
  
  if (pipe(pipe_fds) < 0)
    return -1;

  /* Duplicate stdin and stdout so we can restore them later. */
  stdin_save = dup(STDIN_FILENO);
  stdout_save = dup(STDOUT_FILENO);

  /* Make the write end of the pipe stdout. */
  dup2(pipe_fds[1], STDOUT_FILENO);

  /* Run the program. Its output will be written to the pipe. */
  spawnl(P_WAIT, "/dev/env/DJDIR/bin/ls.exe", "ls.exe", NULL);

  /* Close the write end of the pipe. */
  close(pipe_fds[1]);

  /* Restore stdout. */
  dup2(stdout_save, STDOUT_FILENO);

  /* Make the read end of the pipe stdin. */
  dup2(pipe_fds[0], STDIN_FILENO);

  /* Run another program. Its input will come from the output of the
     first program. */
  spawnl(P_WAIT, "/dev/env/DJDIR/bin/less.exe", "less.exe", "-E", NULL);

  /* Close the read end of the pipe. */
  close(pipe_fds[0]);

  /* Restore stdin. */
  dup2(stdin_save, STDIN_FILENO);
  
  return 0;
@}

@end example
@c -----------------------------------------------------------------------------
@node popen, pow, pipe, Alphabetical List
@unnumberedsec popen
@c From file ./posix/stdio/popen.txh
@findex popen
@subheading Syntax

@example
#include <stdio.h>

FILE *popen(const char *cmd, const char *mode);
@end example

@subheading Description

This function executes the command or program specified by @code{cmd}
and attaches either its input stream or its output stream
to the returned file.  While the file is open, the calling program
can write to the program (if the program was open for writing)
or read the program's output (if the program was opened for reading).
When the program is done, or if you have no more input for it, pass
the file pointer to @code{pclose} (@pxref{pclose}), which terminates
the program. 

Since MS-DOS does not support multitasking, this function actually runs
the entire program when the program is opened for reading, and stores
the output in a temporary file.  @code{pclose} then removes that file. 
Similarly, when you open a program for writing, a temp file holds the
data and @code{pclose} runs the entire program.

The @var{mode} is the same as for @code{fopen} (@pxref{fopen}), except
that you are not allowed to open a pipe for both reading and writing.  A
pipe can be open  either for reading or for writing.

@subheading Return Value

An open file which can be used to read the program's output or write to
the program's input. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
FILE *p = popen("dir", "r");
read_program(p);
pclose(p);
@end example

@c -----------------------------------------------------------------------------
@node pow, pow10, popen, Alphabetical List
@unnumberedsec pow
@c From file ./ansi/math/pow.txh
@findex pow
@subheading Syntax

@example
#include <math.h>

double pow(double x, double y);
@end example

@subheading Description

This function computes @math{@var{x}^@var{y}}, @var{x} raised to the
power @var{y}.

@subheading Return Value

@var{x} raised to the power @var{y}.  If the result overflows a
@code{double} or underflows, @code{errno} is set to @code{ERANGE}.  If
@var{y} is @code{NaN}, the return value is @code{NaN} and @code{errno}
is set to @code{EDOM}.  If @var{x} and @var{y} are both 0, the return
value is 1, but @code{errno} is set to @code{EDOM}.  If @var{y} is a
positive or a negative Infinity, the following results are returned,
depending on the value of @var{x}:

@table @asis
@item @var{x} negative
the return value is @code{NaN} and @code{errno} is set to @code{EDOM}.

@item absolute value of @var{x} less than 1 and @var{y} is @code{+Inf}
@itemx absolute value of @var{x} greater than 1 and @var{y} is @code{-Inf}
the return value is zero.

@item absolute value of @var{x} less than 1 and @var{y} is @code{-Inf}
@itemx absolute value of @var{x} greater than 1 and @var{y} is @code{+Inf}
the return value is @code{+Inf}.

@item absolute value of @var{x} is 1
the return value is @code{NaN} and @code{errno} is set to @code{EDOM}.
@end table


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node pow10, pow2, pow, Alphabetical List
@unnumberedsec pow10
@c From file ./ansi/math/pow10.txh
@findex pow10
@subheading Syntax

@example
#include <math.h>

double pow10(double x);
@end example

@subheading Description

This function computes 10 to the power of @var{x}, @math{10^x}.

@subheading Return Value

10 to the @var{x} power.  If the value of @var{x} is finite, but so
large in magnitude that @math{10^x} cannot be accurately represented by
a @code{double}, the return value is the nearest representable !
@code{double} (possibly, an @code{Inf}), and @code{errno} is set to
@code{ERANGE}.  If @var{x} is either a positive or a negative infinity,
the result is either @code{+Inf} or zero, respectively, and @code{errno}
is not changed.  If @var{x} is a @code{NaN}, the return value is
@code{NaN} and @code{errno} is set to @code{EDOM}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node pow2, powi, pow10, Alphabetical List
@unnumberedsec pow2
@c From file ./ansi/math/pow2.txh
@findex pow2
@subheading Syntax

@example
#include <math.h>

double pow2(double x);
@end example

@subheading Description

This function computes 2 to the power of @var{x}, @math{2^x}.

@subheading Return Value

2 to the @var{x} power.  If the value of @var{x} is finite, but so large
in magnitude that @math{2^x} cannot be accurately represented by a
@code{double}, the return value is the nearest representable
@code{double} (possibly, an @code{Inf}), and @code{errno} is set to
@code{ERANGE}.  If @var{x} is either a positive or a negative infinity,
the result is either @code{+Inf} or zero, respectively, and @code{errno}
is not changed.  If @var{x} is a @code{NaN}, the return value is
@code{NaN} and @code{errno} is set to @code{EDOM}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node powi, _preserve_fncase, pow2, Alphabetical List
@unnumberedsec powi
@c From file ./compat/math/powi.txh
@findex powi
@subheading Syntax

@example
#include <math.h>

double powi(double x, int iy);
@end example

@subheading Description

This function computes @math{x^iy}, where @var{iy} is an integer number.
It does so by an optimized sequence of squarings and multiplications.
For integer values of exponent, it is always faster to call @code{powi}
than to call @code{pow} with the same arguments, even if @var{iy} has a
very large value.  For small values of @var{iy}, @code{powi} is
@emph{much} faster than @code{pow}.

@subheading Return Value

@var{x} raised to the @var{iy} power.  If @var{x} and @var{iy} are both
zero, the return value is 1.  If @var{x} is equal to zero, and @var{iy}
is negative, the return value is @code{Inf}.  This function never sets
@code{errno}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _preserve_fncase, PRI, powi, Alphabetical List
@unnumberedsec _preserve_fncase
@c From file ./dos/lfn/_use_lfn.txh
@findex _preserve_fncase
@vindex FNCASE@r{ environment variable}
@vindex LFN@r{ environment variable, and file-name case}
@subheading Syntax
 
@example
#include <fcntl.h>

char _preserve_fncase (void);
@end example

@subheading Description

This function returns a non-zero value if letter-case in filenames
should be preserved.  It is used by library functions that get filenames
from the operating system (like @code{readdir}, @code{_fixpath} and
others).  The usual behavior of these functions (when
@code{_preserve_fncase} returns zero) is to down-case 8+3 DOS-style
filenames, but leave alone the letter-case in long filenames when these
are supported (@pxref{_use_lfn}).  This can be changed by either setting
@code{_CRT0_FLAG_PRESERVE_FILENAME_CASE} bit in the
@code{_crt0_startup_flags} variable (@pxref{_crt0_startup_flags}), or by
setting the @code{FNCASE} environment variable to @kbd{Y} at run time.
You might need such a setup e.g. on Windows 95 if you want to see files
with names like @file{README} and @file{FAQ} listed in upper-case (for
this to work, you will have to manually rename all the other files with
8+3 DOS-style names to lower-case names).  When the case in filenames is
preserved, all filenames will be returned in upper case on MSDOS (and
other systems that don't support long filenames), or if the environment
variable @code{LFN} is set to @kbd{N} on systems that support LFN.  That
is because this is how filenames are stored in the DOS directory entries.

@subheading Return value

Zero when 8+3 filenames should be converted to lower-case, non-zero
otherwise.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable



@c -----------------------------------------------------------------------------
@node PRI, printf, _preserve_fncase, Alphabetical List
@unnumberedsec PRI
@c From file ./c99/inttypes/pri.txh
@subheading Syntax

@example
#include <inttypes.h>
@end example

@subheading Description

The @code{PRI} family of macros allows integers to be displayed
in a portable manner using the @code{printf} family of functions
(@pxref{printf}).  They include a conversion qualifier, to specify
the width of the type (e.g.: @code{l} for @code{long}),
and the conversion type specifier (e.g.: @code{d} for decimal
display of integers).

The @code{PRI} family of macros should be used with the types defined
in the header @code{<stdint.h>}.  For example: @code{int8_t},
@code{uint_fast32_t}, @code{uintptr_t}, @code{intmax_t}.

Below @var{N} can be 8, 16, 32 or 64.  The @code{PRI} macros are:

@table @code

@item PRId@var{N}
@itemx PRIi@var{N}

The @code{d} and @code{i} type conversion specifiers
for a type @code{int@var{N}_t} of @var{N} bits.

@item PRIdLEAST@var{N}
@itemx PRIiLEAST@var{N}

The @code{d} and @code{i} type conversion specifiers
for a type @code{int_least@var{N}_t} of @var{N} bits.

@item PRIdFAST@var{N}
@itemx PRIiFAST@var{N}

The @code{d} and @code{i} type conversion specifiers
for a type @code{int_fast@var{N}_t} of @var{N} bits.

@item PRIdMAX
@itemx PRIiMAX

The @code{d} and @code{i} type conversion specifiers
for a type @code{intmax_t}.

@item PRIdPTR
@itemx PRIiPTR

The @code{d} and @code{i} type conversion specifier
for a type @code{intptr_t}.

@item PRIo@var{N}
@itemx PRIu@var{N}
@itemx PRIx@var{N}
@itemx PRIX@var{N}

The @code{o}, @code{u}, @code{x} and @code{X} type conversion specifiers
for a type @code{uint@var{N}_t} of @var{N} bits.

@item PRIoLEAST@var{N}
@itemx PRIuLEAST@var{N}
@itemx PRIxLEAST@var{N}
@itemx PRIXLEAST@var{N}

The @code{o}, @code{u}, @code{x} and @code{X} type conversion specifiers
for a type @code{uint_LEAST@var{N}_t} of @var{N} bits.

@item PRIoFAST@var{N}
@itemx PRIuFAST@var{N}
@itemx PRIxFAST@var{N}
@itemx PRIXFAST@var{N}

The @code{o}, @code{u}, @code{x} and @code{X} type conversion specifiers
for a type @code{uint_FAST@var{N}_t} of @var{N} bits.

@item PRIoMAX
@itemx PRIuMAX
@itemx PRIxMAX
@itemx PRIXMAX

The @code{o}, @code{u}, @code{x} and @code{X} type conversion specifiers
for a type @code{uintmax_t}.

@item PRIoPTR
@itemx PRIuPTR
@itemx PRIxPTR
@itemx PRIXPTR

The @code{o}, @code{u}, @code{x} and @code{X} type conversion specifiers
for a type @code{uintptr_t}.

@end table

@subheading Return Value

Not applicable.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable


@subheading Example

@example
uintmax_t foo = 500;

printf("foo is %" PRIuMAX " in decimal and 0x%" PRIxMAX " in hex.\n",
       foo, foo);
@end example
@c -----------------------------------------------------------------------------
@node printf, psignal, PRI, Alphabetical List
@unnumberedsec printf
@c From file ./ansi/stdio/printf.txh
@findex printf
@subheading Syntax

@example
#include <stdio.h>

int printf(const char *format, @dots{});
@end example

@subheading Description

Sends formatted output from the arguments (@dots{}) to @code{stdout}.

The format string contains regular characters to print, as well as
conversion specifiers, which begin with a percent symbol.  Conversions can
be applied to the @var{n}th argument after the format string in the argument list,
rather than to the next unused argument.  In this case, the conversion
specifier character @code{%} is replaced by the sequence @code{%@var{n}$}, where
@var{n} is a decimal integer in the range [@code{1}, @code{number of the last argument}],
giving the position of the argument in the argument list.  The format string
can contain either numbered argument conversion specifiers (that is, @code{%@var{n}$}
and @code{*@var{m}$}), or unnumbered argument conversion specifiers (that is @code{%}
and @code{*}), but not both.  The only exception to this is that @code{%%} can
be mixed with @code{%@var{n}$} form.  When numbered argument specifications are
used, specifying the @var{n}th argument requires that all the leading arguments,
from the first to the (@var{n}-1)th, are specified in the format string.  In format
strings containing the @code{%@var{n}$} form of conversion specification, numbered
arguments in the argument list can be referenced from the format string as many
times as required.

Each conversion specifier contains the following fields:

@itemize @bullet

@item

an optional flag, which may alter the conversion:

@table @code

@item '

Formats the integer portion of the result of a decimal conversion (%i, %d, %u,
%f, %F, %g and %G) using the non-monetary thousends' grouping character.

@item -

left-justify the field.

@item +

Force a @code{+} sign on positive numbers.

@item space

To leave a blank space where a plus or minus sign would have been. 

@item #

Alternate conversion - prefix octal numbers with @code{0}, hexadecimal
numbers with @code{0x} or @code{0X}, or force a trailing decimal point
if a floating point conversion would have omitted it. 

@item 0

To pad numbers with leading zeros.

@end table

@item

A field width specifier, which specifies the minimum width of the field. 
This may also be an asterisk (@code{*}), which means that the actual
width will be obtained from the next argument.  If the argument is
negative, it supplies a @code{-} flag and a positive width. 
In format strings containing the @code{%@var{n}$} form of a conversion
specifier, a field width can be indicated by the sequence @code{*@var{m}$},
where @var{m} is a decimal integer in the range [@code{1}, @code{number of the last argument}],
giving the position in the argument list (after the format argument) of
an integer argument containing the field width.

@item

An optional decimal point and a precision.  This may also be an
asterisk, but a negative argument for it indicates a precision of zero. 
The precision specifies the minimum number of digits to print for an
integer, the number of fraction digits for a floating point number (max
for @code{g} or @code{G}, actual for others), or the maximum number of
characters for a string. 
In format strings containing the @code{%@var{n}$} form of a conversion
specifier, a precision can be indicated by the sequence @code{*@var{m}$},
where @var{m} is a decimal integer in the range [@code{1}, @code{number of the last argument}],
giving the position in the argument list (after the format argument) of
an integer argument containing the precision.

@item

An optional conversion qualifier, which may be:

@table @code
@item hh
to specify @code{char};

@item h
to specify @code{short} integers;

@item j
to specify @code{intmax_t} or @code{uintmax_t} integers;

@item l
to specify doubles or @code{long} integers, @code{wint_t} or @code{wchar_t};

@item ll
(two lower-case ell letters) to specify @code{long long} integers;
to specify @code{long} doubles, although this is non-standard;

@item L
to specify @code{long} doubles;

@item t
to specify @code{ptrdiff_t};

@item z
to specify @code{size_t}.
@end table

@item

The conversion type specifier:

@table @code

@item a
@itemx A

A floating point number (float or double) printed in the style
@samp{"[-]0xh.hhhhp[+|-]d"}, where @samp{h} represents a hexadecimal
digit, @samp{d} represents a decimal digit and @samp{p} stands for the
base 2.  For long double, use @code{"La"} or @code{"LA"}.  The case of
the exponent, the case of the letters @code{"abcdef"} and the case of
@code{"x"} matches the specifier case.  The representation always has
an exponent.

@item c

A single character.

@item d

A signed integer.

@item D

A signed long integer.  This is non-standard and obsolete.
Please use @code{ld} instead.

@item e
@itemx E

A floating point number (float or double).  For long double, use
@code{"Le"} or @code{"LE"}.  The exponent case matches the specifier
case.  The representation always has an exponent.

@item f
@itemx F

A floating point number (float or double).  For long double, use
@code{"Lf"}.  The representation never has an exponent.

@item g
@itemx G

A floating point number (float or double).  For long double, use
@code{"Lg"} or @code{"LG"}.  The exponent case matches the specifier
case.  The representation has an exponent if it needs one.

@item i

A signed integer.

@item n

The next argument is a pointer to an integer, and the number of
characters generated so far is stored in that integer. 

@item o

A unsigned integer, printed in base 8 instead of base 10.

@item O

A unsigned long integer, printed in base 8 instead of base 10.
This is non-standard and obsolete.  Please use @code{lo} instead.

@item p

A pointer.  This is printed with an @code{x} specifier.

@item s

A @code{NULL}-terminated string.

@item u

An unsigned integer.

@item U

An unsigned long integer.  This is non-standard and obsolete.
Please use @code{lu} instead.

@item x
@itemx X

An unsigned integer, printed in base 16 instead of base 10.  The case of
the letters used matches the specifier case. 

@item %

A single percent symbol is printed.

@end table

@end itemize

@subheading Return Value

The number of characters written.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99 (see note 1); (see note 2) (see note 3)
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable

@noindent
Notes:

@enumerate
@item
The @code{hh}, @code{j}, @code{t} and @code{z}
conversion qualifiers first appeared in the ANSI C99 standard.

@item
The @code{D}, @code{O} and @code{U} conversion type
specifiers are non-standard.  gcc may generate warnings, if you use them.

@item
The @code{a}, @code{A} and @code{F} conversion type
specifiers first appeared in the ANSI C99 standard.

@end enumerate

@subheading Example

@example
printf("%-3d %10.2f%% Percent of %s\n", index, per[index], name[index]);
@end example

The following statement can be used to print date and time
using language-independent format:

@example
printf(format, weekday, month, day, hour, precision, min);
@end example


For American usage, the format string could look like:

@example
"%s, %s %d, %d:%.*d\n"
@end example

The integer precision has the value 2.
The above example will produce the following message:

@example
Sunday, October 27, 9:09
@end example


For German usage, the format string could look like:

@example
"%1$s, %3$d. %2$s, %4$d:%6$.*5$d\n"
@end example

The above example will produce the following message:

@example
Sonntag, 27. Oktober, 9:09
@end example
@c -----------------------------------------------------------------------------
@node psignal, _put_path, printf, Alphabetical List
@unnumberedsec psignal
@c From file ./compat/signal/siglist.txh
@findex psignal
@subheading Syntax

@example
#include <signal.h>

extern char *sys_siglist[];
void psignal (int sig, const char *msg);
@end example

@subheading Description

This function produces a message on the standard error stream describing
the signal given by its number in @var{sig}.  It prints the string
pointed to by @var{msg}, then the name of the signal, and a newline.

The names of signals can be retrieved using the array
@code{sys_siglist}, with the signal number serving as an index into this
array.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  #include <signal.h>

  void sig_catcher (int sig)
  @{
    psignal (progname, sig);
    return;
  @}
@end example
@c -----------------------------------------------------------------------------
@node _put_path, putc, psignal, Alphabetical List
@unnumberedsec _put_path
@c From file ./dos/io/putpath.txh
@findex _put_path
@findex _put_path2

@subheading Syntax

@example
#include <libc/dosio.h>

int _put_path(const char *path);
int _put_path2(const char *path, int offset);
@end example

@subheading Description

These functions are used internally by all low-level library functions
that need to pass file names to DOS.  @code{_put_path} copies its
argument @var{path} to the @dfn{transfer buffer}
(@pxref{_go32_info_block}) starting at the beginning of the transfer
buffer; @code{_put_path2} does the same except that it puts the file
name starting at @var{offset} bytes from the beginning of the transfer
buffer.

These functions are meant to be called by low-level library functions,
not by applications.  You should only call them if you know what you are
doing.  In particular, if you call any library function between a call
to @code{_put_path} or @code{_put_path2} and the call to a DOS function
that uses the file name, the file name in the transfer buffer could be
wiped out, corrupted or otherwise changed.  You @emph{have} been
warned!

Some constructs in file names are transformed while copying them, to
allow transparent support for nifty features.  Here's the list of these
transformations:

@itemize @bullet{}
@item Multiple forward slashes are collapsed into a single slash.

Unix treats multiple slashes as a single slash, so some ported programs
pass names like @file{c:/foo//bar} to library functions.  DOS functions
choke on such file names, so collapsing the slashes prevents these names
from failing.

@item Trailing slashes are removed, except for root directories.

Various DOS calls cannot cope with file names like @file{c:/foo/}; this
feature solves this problem.

@item Translation of Unix device names.

Unix @file{/dev/null} is mapped to DOS-standard @file{NUL}, and Unix
@file{/dev/tty} to DOS-standard @file{CON}.  This provides for
transparent support of these special devices, e.g. in Unix shell
scripts.

@item Translation of DOS device names.

Any file name which begins with @file{/dev/} or @file{@var{x}:/dev/}
(where @var{x}: is any valid DOS drive letter) has the @file{/dev/} or
@file{@var{x}:/dev/} prefix removed (if the @file{/dev/} directory does
not exist), and the rest is passed to DOS.
This is because some DOS functions don't recognize device names unless
they are devoid of the drive and directory specifications, and programs
could add a drive and a directory if they convert a name like
@file{/dev/con} to a fully-qualified path name.
Because of the different behavior when the @file{/dev/} directory
exists, you should only add the prefix @file{/dev/} to your DOS device 
names if necessary and be sure that the @file{/dev/} does not exist.
Due to the additional overhead of checking if @file{/dev/} exists, 
functions working with DOS device names with the prefix will be slower.

@item @file{/dev/x/} is translated into @file{x:/}.

This allows to use Unix-style absolute path names that begin with a
slash, instead of DOS-style names with a drive letter.  Some Unix
programs and shell scripts fail for file names that include colons,
which are part of the drive letter specification; this feature allows to
work around such problems by using e.g. @file{/dev/c/} where @file{c:/}
would fail.

@item @file{/dev/env/@var{foo}/} is replaced by the value of the environment
variable @var{foo}.

(In other words, you can think of environment variables as if they were
sub-directories of a fictitious directory @file{/dev/env}.)

This allows to use environment variable names inside path names compiled
into programs, and have them transparently expanded at run time.  For
example, @file{/dev/env/DJDIR/include} will expand to the exact path
name of the DJGPP include directory, no matter where DJGPP is installed
on the machine where the program runs.  (The value of @code{DJDIR} is
computed by the DJGPP startup code and pushed into the environment of
every DJGPP program before @code{main} is called.)

Note that environment variables are case-sensitive, so
@file{/dev/env/foo} and @file{/dev/env/FOO} are @strong{not} the same.
DOS shells usually upcase the name of the environment variable if you
set it with the built-in command @samp{SET}, so if you type
e.g. @samp{SET foo=bar}, the shell defines a variable named @code{FOO}.

If the environment variable is undefined, it will expand into an empty
string.  The expansion is done recursively, so environment variables may
reference other environment variables using the same @file{/dev/env/}
notation.  For example, if the variable @code{HOME} is set to
@file{/dev/env/DJDIR/home}, and DJGPP is installed in
@file{c:/software/djgpp}, then @file{/dev/env/HOME/sources} will expand
to @file{c:/software/djgpp/home/sources}.

It is possible to supply a default value, to be used if the variable is
not defined, or has an empty value.  To this end, put the default value
after the name of the variable and delimit it by @samp{~}, like in
@file{/dev/env/DJDIR~c:/djgpp~/include}.

If you need to include a literal character @samp{~} in either the
environment variable name or in the default value that replaces it, use
two @samp{~}s in a row.  For example, @file{/dev/env/FOO~~} will expand
to the value of the variable @code{FOO~}.  Likewise,
@file{/dev/env/FOO~~BAR~foo~~baz~} will expand to the value of the
variable @code{FOO~BAR} if it is defined and nonempty, and to
@file{foo~baz} otherwise.  Leading @samp{~} in the default value isn't
supported (it is interpreted as part of the preceding variable name).

The default value may also reference (other) environment variables, but
nested default values can get tricky.  For example,
@file{/dev/env/foo~/dev/env/bar~} will work, but
@file{/dev/env/foo~/dev/env/bar~baz~~} will @strong{not}.  To use nested
default values, you need to double the quoting of the @samp{~}
characters, like in @file{/dev/env/foo~/dev/env/bar~~baz~~~}.
@end itemize

@subheading Return Value

Both functions return the offset into the transfer buffer of the
terminating null character that ends the file name.

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

These functions are meant to be called by low-level library functions,
not by applications.  You should only call them if you know what you are
doing.  In particular, if you call any library function between a call
to @code{_put_path} or @code{_put_path2} and the call to a DOS function
that uses the file name, the file name in the transfer buffer could be
wiped out, corrupted and otherwise changed.  You @emph{have} been
warned!

@example
 __dpmi_regs r;

 _put_path("/dev/c/djgpp/bin/");
 r.x.ax = 0x4300;  /* get file attributes */
 r.x.ds = __tb >> 4;
 r.x.dx = __tb & 0x0f;
 __dpmi_int(0x21, &r);
@end example


@c -----------------------------------------------------------------------------
@node putc, putch, _put_path, Alphabetical List
@unnumberedsec putc
@c From file ./ansi/stdio/putc.txh
@findex putc
@subheading Syntax

@example
#include <stdio.h>

int putc(int c, FILE *file);
@end example

@subheading Description

This function writes one character to the given @var{file}.

@subheading Return Value

The character written.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
while ((c=getc(stdin)) != EOF)
  putc(c, stdout);
@end example

@c -----------------------------------------------------------------------------
@node putch, putchar, putc, Alphabetical List
@unnumberedsec putch
@c From file ./pc_hw/co80/conio.txh
@findex putch
@subheading Syntax

@example
#include <conio.h>

int putch(int _c);
@end example

@subheading Description

Put the character @var{_c} on the screen at the current cursor
position.  The special characters return, linefeed, bell, and
backspace are handled properly, as is line wrap and scrolling.  The
cursor position is updated.

@subheading Return Value

The character is returned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node putchar, putenv, putch, Alphabetical List
@unnumberedsec putchar
@c From file ./ansi/stdio/putchar.txh
@findex putchar
@subheading Syntax

@example
#include <stdio.h>

int putchar(int c);
@end example

@subheading Description

This is the same as @code{fputc(c, stdout)}.  @xref{fputc}.

@subheading Return Value

The character written.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
while ((c = getchar()) != EOF)
  putchar(c);
@end example

@c -----------------------------------------------------------------------------
@node putenv, puts, putchar, Alphabetical List
@unnumberedsec putenv
@c From file ./compat/stdlib/putenv.txh
@findex putenv
@subheading Syntax

@example
#include <stdlib.h>

int putenv(char *env);
@end example

@subheading Description

This function adds an entry to the program's environment.  The string
passed must be of the form @code{NAME}=@code{VALUE}.  Any existing value
for the environment variable is gone. 

@code{putenv} will copy the string passed to it, and will
automatically free any existing string already in the environment.
Keep this in mind if you alter the environment yourself.  The string
you pass is still your responsibility to free.  Note that most
implementations will not let you free the string you pass, resulting
in memory leaks.

@subheading Return Value

Zero on success, nonzero on failure;  @code{errno} will be set to the
relevant error code: currently only @code{ENOMEM} (insufficient memory)
is possible.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
This function is new to the Posix 1003.1-200x draft
@end enumerate

@subheading Example

@example
putenv("SHELL=ksh.exe");
@end example

@c -----------------------------------------------------------------------------
@node puts, puttext, putenv, Alphabetical List
@unnumberedsec puts
@c From file ./ansi/stdio/puts.txh
@findex puts
@subheading Syntax

@example
#include <stdio.h>

int puts(const char *string);
@end example

@subheading Description

This function writes @var{string} to @code{stdout}, and then writes a
newline character. 

@subheading Return Value

Nonnegative for success, or @code{EOF} on error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
puts("Hello, there");
@end example

@c -----------------------------------------------------------------------------
@node puttext, putw, puts, Alphabetical List
@unnumberedsec puttext
@c From file ./pc_hw/co80/conio.txh
@findex puttext
@subheading Syntax

@example
#include <conio.h>

int puttext(int _left, int _top, int _right, int _bottom,
            void *_source);
@end example

@subheading Description

The opposite of @ref{gettext}.

@subheading Return Value

1 on success, zero on error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node putw, pwrite, puttext, Alphabetical List
@unnumberedsec putw
@c From file ./ansi/stdio/putw.txh
@findex putw
@subheading Syntax

@example
#include <stdio.h>

int putw(int x, FILE *file);
@end example

@subheading Description

Writes a single 32-bit binary word @var{x} in native format to
@var{file}.  This function is provided for compatibility with other
32-bit environments, so it writes a 32-bit @code{int}, not a 16-bit
@code{short}, like some 16-bit DOS compilers do.

@subheading Return Value

The value written, or @code{EOF} for end-of-file or error.  Since
@code{EOF} is a valid integer, you should use @code{feof} or
@code{ferror} to detect this situation. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
putw(12, stdout);
@end example

@c -----------------------------------------------------------------------------
@node pwrite, qsort, putw, Alphabetical List
@unnumberedsec pwrite
@c From file ./posix/unistd/pwrite.txh
@findex pwrite
@subheading Syntax

@example
#include <unistd.h>

int pwrite(int file, const void *buffer, size_t count, off_t offset);
@end example

@subheading Description

This function writes @var{count} bytes from @var{buffer} to
@var{file} at position @var{offset}.  It returns the number of bytes
actually written.  It will return zero or a number less than
@var{count} if the disk is full, and may return less than @var{count}
even under valid conditions.

Note that if @var{file} is a text file, @code{pwrite} may write more
bytes than it reports. 

If @var{count} is zero, the function does nothing and returns zero.
Use @code{_write} if you want to actually ask DOS to write zero bytes.

The precise behavior of @code{pwrite} when the target filesystem is full
are somewhat troublesome, because DOS doesn't fail the underlying system
call.  If your application needs to rely on @code{errno} being set to
@code{ENOSPC} in such cases, you need to invoke @code{pwrite} as shown in
an example for @code{write} (@pxref{write}).  In a nutshell, the trick is
to call @code{pwrite} one more time after it returns a value smaller
than the @var{count} parameter; then it will @emph{always} set @code{errno}
if the disk is full.

@subheading Return Value

The number of bytes written, zero at EOF, or -1 on error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable


@subheading Example

@example
const char buf[] = "abc";
const size_t bufsize = strlen(buf);

/* Write out buf, then overwrite 'b' with 'd'. NB: We should check
 * for errors. */
lseek(fd, 0L, SEEK_SET);
write(fd, buf, bufsize);
pwrite(fd, "d", 1, 1);
@end example
@c -----------------------------------------------------------------------------
@node qsort, raise, pwrite, Alphabetical List
@unnumberedsec qsort
@c From file ./ansi/stdlib/qsort.txh
@findex qsort
@subheading Syntax

@example
#include <stdlib.h>

void qsort(void *base, size_t numelem, size_t size,
           int (*cmp)(const void *e1, const void *e2));
@end example

@subheading Description

This function sorts the given array in place.  @var{base} is the address
of the first of @var{numelem} array entries, each of size @var{size}
bytes.  @code{qsort} uses the supplied function @var{cmp} to determine
the sort order for any two elements by passing the address of the two
elements and using the function's return address. 

The return address of the function indicates the sort order:

@table @asis

@item Negative

Element @var{e1} should come before element @var{e2} in the resulting
array. 

@item Positive

Element @var{e1} should come after element @var{e2} in the resulting
array. 

@item Zero

It doesn't matter which element comes first in the resulting array. 

@end table

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
typedef struct @{
  int size;
  int sequence;
@} Item;

int qsort_helper_by_size(const void *e1, const void *e2)
@{
  return ((const Item *)e2)->size - ((const Item *)e1)->size;
@}

Item list[100];

qsort(list, 100, sizeof(Item), qsort_helper_by_size);

int qsort_stringlist(const void *e1, const void *e2)
@{
  return strcmp(*(char **)e1, *(char **)e2);
@}

char *slist[10];

/* alphabetical order */
qsort(slist, 10, sizeof(char *), qsort_stringlist);

@end example

@c -----------------------------------------------------------------------------
@node raise, rand, qsort, Alphabetical List
@unnumberedsec raise
@c From file ./go32/dpmiexcp.txh
@findex raise
@subheading Syntax

@example
#include <signal.h>

int	raise(int sig);
@end example

@subheading Description

This function raises the given signal @var{sig}.
@xref{signal, the list of possible signals}.

@subheading Return Value

0 on success, -1 for illegal value of @var{sig}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable



@c -----------------------------------------------------------------------------
@node rand, rand48, raise, Alphabetical List
@unnumberedsec rand
@c From file ./ansi/stdlib/rand.txh
@findex rand
@subheading Syntax

@example
#include <stdlib.h>

int rand(void);
@end example

@subheading Description

Returns a pseudo-random number between zero and @code{RAND_MAX} (defined
on @file{stdlib.h}).

By default, this function always generates the same sequence of numbers
each time you run the program.  (This is usually desirable when
debugging, or when comparing two different runs.)  If you need to
produce a different sequence on every run, you must seed @code{rand} by
calling @code{srand} (@pxref{srand}) before the first call to
@code{rand}, and make sure to use a different argument to @code{srand}
each time.  The usual technique is to get the argument to @code{srand}
from a call to the @code{time} library function (@pxref{time}), whose
return value changes every second.

To get a random number in the range 0..N, use @code{rand()%(N+1)}.  Note
that the low bits of the @code{rand}'s return value are not very random,
so @code{rand()%N} for small values of @var{N} could be not enough
random.  The alternative, but non-@sc{ansi}, function @code{random} is
better if @var{N} is small.  @xref{random}.

@subheading Return Value

The number.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
/* random pause */
srand(time(0));
for (i=rand(); i; i--);
@end example

@c -----------------------------------------------------------------------------
@node rand48, random, rand, Alphabetical List
@unnumberedsec rand48
@c From file ./compat/stdlib/rand48.txh
@findex drand48
@findex erand48
@findex lrand48
@findex nrand48
@findex mrand48
@findex jrand48
@findex srand48
@findex seed48
@findex lcong48
@subheading Syntax

@example
#include <stdlib.h>

double drand48(void);
double erand48(unsigned short state[3]);
unsigned long lrand48(void);
unsigned long nrand48(unsigned short state[3]);
long mrand48(void);
long jrand48(unsigned short state[3]);
void srand48(long seed);
unsigned short *seed48(unsigned short state_seed[3]);
void lcong48(unsigned short param[7]);
@end example

@subheading Description

This is the family of @code{*rand48} functions.  The basis for these functions
is the linear congruential formula @math{X[n+1] = (a*X[n] + c) mod 2^48,
n >= 0}.  a = 0x5deece66d and c = 0xb at start and after a call to either
@code{srand48} or @code{seed48}.  A call to @code{lcong48}
changes a and c (and the internal state). 

@code{drand48} and @code{erand48} return @code{double}s uniformly
distributed in the interval [0.0, 1.0). 

@code{lrand48} and @code{nrand48} return @code{unsigned long}s
uniformly distributed in the interval [0, 2^31).

@code{mrand48} and @code{jrand48} return @code{long}s uniformly
distributed in the interval [-2^31, 2^31). 

@code{erand48}, @code{jrand48} and @code{nrand48} requires the
state of the random generator to be passed.  

@code{drand48}, @code{lrand48} and @code{mrand48} uses an
internal state (common with all three functions) which should be
initialized with a call to one of the functions @code{srand48},
@code{seed48} or @code{lcong48}. 

@code{srand48} sets the high order 32 bits to the argument
@var{seed}.  The low order 16 bits are set to the arbitrary value
0x330e. 

@code{seed48} sets the internal state according to the argument
@var{state_seed} (@code{@var{state_seed}[0]} is least significant).
The previous state of the random generator is saved in an internal
(static) buffer, to which a pointer is returned. 

@code{lcong48} sets the internal state to @code{@var{param}[0-2]}, a to 
@code{@var{param}[3-5]} (@code{@var{param}[0]} and @code{@var{param}[3]}
are least significant) and c to @code{@var{param}[6]}. 

@subheading Return Value

A random number.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
#include <stdio.h>
#include <stdlib.h>
#include <time.h>

int main(void)
@{

  srand48(time(NULL));
  printf("%.12f is a random number in [0.0, 1.0).\n", drand48());

  exit(0);
@}

@end example
@c -----------------------------------------------------------------------------
@node random, rawclock, rand48, Alphabetical List
@unnumberedsec random
@c From file ./compat/stdlib/random.txh
@findex random
@subheading Syntax

@example
#include <stdlib.h>

long random(void);
@end example

@subheading Description

Returns a random number in the range 0..MAXINT.

@subheading Return Value

0 .. MAXINT

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
 /* Produce a random integer between 0 and 199.  */
 int random_number = random () % 200;
@end example

@c -----------------------------------------------------------------------------
@node rawclock, _rdtsc, random, Alphabetical List
@unnumberedsec rawclock
@c From file ./compat/time/rawclock.txh
@findex rawclock
@subheading Syntax

@example
#include <time.h>

unsigned long rawclock(void);
@end example

@subheading Description

Returns the number of clock tics (18.2 per second) since midnight. 

@subheading Return Value

The number of tics.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
/* wait 1/4 second */
int i = rawclock()+5;
while (rawclock()<i);
@end example

@c -----------------------------------------------------------------------------
@node _rdtsc, read, rawclock, Alphabetical List
@unnumberedsec _rdtsc
@c From file ./pc_hw/timer/rdtsc.txh
@findex _rdtsc
@subheading Syntax

@example
#include <time.h>

unsigned long long _rdtsc(void);
@end example

@subheading Description

This function invokes the hardware instruction @code{rdtsc} which is
only supported on some processors.  It is incremented once per clock
cycle on the main processor.  It is a high precision timer which is
useful for timing code for optimization.  You should not use this 
function in distributed programs without protecting for processors 
which do not support the instruction.  For a general purpose high
precision timer see @code{uclock} (@pxref{uclock}).

@subheading Return Value

The number of processor cycles.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
#include <stdio.h>
#include <time.h>
#include <signal.h>
#include <setjmp.h>
#include <sys/exceptn.h>

/* Catch rdtsc exception and always return 0LL */
void catch_rdtsc(int val)
@{
  short *eip = (short *)__djgpp_exception_state->__eip;
  if(*eip == 0x310f) @{
    __djgpp_exception_state->__eip += 2;
    __djgpp_exception_state->__edx = 0;
    longjmp(__djgpp_exception_state, 0);
  @}
  return;
@}

int main(void)
@{
  unsigned long long t;
  
  signal(SIGILL, catch_rdtsc);
  t = _rdtsc();
  printf("Timer value: %llu\n",t);
  
  return 0;
@}
@end example

@c -----------------------------------------------------------------------------
@node read, _read, _rdtsc, Alphabetical List
@unnumberedsec read
@c From file ./posix/unistd/read.txh
@findex read
@subheading Syntax

@example
#include <unistd.h>

ssize_t read(int fd, void *buffer, size_t length);
@end example

@subheading Description

This function reads at most @var{length} bytes from file @var{fd} into
@var{buffer}.  Note that in some cases, such as end-of-file conditions
and text files, it may read less than the requested number of bytes. 
At end-of-file, @code{read} will read exactly zero bytes.

Directories cannot be read using @code{read} --- use @code{readdir}
instead.

@subheading Return Value

The number of bytes read, zero meaning end-of-file, or -1 for an error. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
char buf[10];
int r = read(0, buf, 10);
@end example

@c -----------------------------------------------------------------------------
@node _read, read_child, read, Alphabetical List
@unnumberedsec _read
@c From file ./dos/io/_read.txh
@findex _read
@subheading Syntax

@example
#include <io.h>

ssize_t _read(int fildes, void *buf, size_t nbyte);
@end example

@subheading Description

This is a direct connection to the MS-DOS read function call, int
0x21, %ah = 0x3f.  No conversion is done on the data; it is read as
raw binary data. This function can be hooked by the
@xref{File System Extensions}. If you don't want this, you should
use @xref{_dos_read}.

@subheading Return Value

The number of bytes read.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node read_child, read_sel_addr, _read, Alphabetical List
@unnumberedsec read_child
@c From file ./debug.txh
@findex read_child

@subheading Syntax

@example
#include <debug/dbgcom.h>

int read_child (unsigned child_addr, void *buf, unsigned len);
@end example

@subheading Description

This function reads the memory of the debugged process starting at
address @var{child_addr} for @var{len} bytes, and copies the data read
to the buffer pointed to by @var{buf}.  It is used primarily to save the
original instruction at the point where a breakpoint instruction is
inserted (to trigger a trap when the debuggee's code gets to that
point).  @xref{write_child}.

@subheading Return Value

The function return zero if it has successfully transferred the data,
non-zero otherwise (e.g., if the address in @var{child_addr} is outside
the limits of the debuggee's code segment.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable



@c -----------------------------------------------------------------------------
@node read_sel_addr, readdir, read_child, Alphabetical List
@unnumberedsec read_sel_addr
@c From file ./debug.txh
@findex read_sel_addr

@subheading Syntax

@example
#include <debug/dbgcom.h>

int read_sel_addr (unsigned offset, void *buf, unsigned len,
                   unsigned sel);
@end example

@subheading Description

This function reads the memory starting at offset @var{offset} in
selector @var{sel} for @var{len} bytes, and copies the data read to the
buffer pointed to by @var{buf}.  @xref{write_sel_addr}.

@subheading Return Value

The function return zero if it has successfully transferred the data,
non-zero otherwise (e.g., if the address in @var{offset} is outside
the limits of the segment whose selector is @var{sel}).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable



@c -----------------------------------------------------------------------------
@node readdir, readlink, read_sel_addr, Alphabetical List
@unnumberedsec readdir
@c From file ./posix/dirent/readdir.txh
@findex readdir
@tindex dirent@r{ structure}
@subheading Syntax

@example
#include <dirent.h>

struct dirent *readdir(DIR *dir);
@end example

@subheading Description

This function reads entries from a directory opened by @code{opendir}
(@pxref{opendir}).  It returns the information in a static buffer with
this format:

@example
struct dirent @{
  unsigned short d_namlen;  /* The length of the name (like strlen) */
  char d_name[MAXNAMLEN+1]; /* The name */
  mode_t d_type;            /* The file's type */
@};
@end example

Note that some directory entries might be skipped by @code{readdir},
depending on the bits set in the global variable
@code{__opendir_flags}.  @xref{opendir, __opendir_flags, opendir}.

The possible values of the @code{d_type} member are:

@table @code
@item DT_REG
This is a regular file.
@item DT_BLK
The file is a block device.
@item DT_CHR
The file is a character device.
@item DT_DIR
The file is a directory.
@item DT_FIFO
This is a pipe (never happens in DJGPP).
@item DT_LABEL
The file is a volume label.
@item DT_LNK
The file is a symlink.
@item DT_SOCK
The file is a socket.
@item DT_UNKNOWN
The file's type is unknown.  This value is put into the @code{d_type}
member if the exact file's type is too expensive to compute.  If the
@code{__OPENDIR_NO_D_TYPE} flag is set in the global variable
@code{__opendir_flags}, @emph{all} files get marked with
@code{DT_UNKNOWN}.
@end table

The macro @code{DTTOIF} (@pxref{DTTOIF}) can be used to convert the
@code{d_type} member to the equivalent value of the @code{st_mode}
member of @code{struct stat}, see @ref{stat}.

@subheading Return Value

A pointer to a static buffer that is overwritten with each call.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
The @code{__opendir_flags} variable is DJGPP-specific.  The @code{d_type} member is an extension available on some systems such as GNU/Linux.
@end enumerate

@subheading Example

@example
DIR *d = opendir(".");
struct dirent *de;
while (de = readdir(d))
  puts(de->d_name);
closedir(d);
@end example

@c -----------------------------------------------------------------------------
@node readlink, readv, readdir, Alphabetical List
@unnumberedsec readlink
@c From file ./compat/unistd/readlink.txh
@findex readlink
@subheading Syntax

@example
#include <unistd.h>

int readlink(const char *filename, char *buffer, size_t size);
@end example

@subheading Description
MSDOS doesn't support symbolic links but DJGPP emulates them.
This function checks if @var{filename} is a DJGPP symlink and
the file name that the links points to is copied into buffer,
up to maximum @var{size} characters.  
Portable applications should not assume that @var{buffer} is
terminated with @code{'\0'}.

@subheading Return Value

Number of copied characters; value -1 is returned in case of
error and @code{errno} is set.  When value returned is equal to 
@var{size}, you cannot determine if there was enough room to 
copy whole name.  So increase @var{size} and try again.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char buf[FILENAME_MAX + 1];
if (readlink("/dev/env/DJDIR/bin/sh.exe", buf, FILENAME_MAX) == -1)
   if (errno == EINVAL)
      puts("/dev/env/DJDIR/bin/sh.exe is not a symbolic link.");
@end example

@c -----------------------------------------------------------------------------
@node readv, realloc, readlink, Alphabetical List
@unnumberedsec readv
@c From file ./posix/sys/uio/readv.txh
@findex readv
@tindex iovec@r{ structure}

@subheading Syntax

@example
#include <sys/uio.h>

ssize_t readv(int fd, const struct iovec *iov, int iovcnt);
@end example

@subheading Description

@code{readv} performs a scatter-gather read from the specified file
descriptor @var{fd}.  The data is written into a group of buffers described
by the array @var{iov} with @var{iovcnt} entries in a similar way to
@code{read} (@pxref{read, , read, libc}).

@code{struct iovec} is defined as follows:

@example
struct iovec @{
  void   *iov_base; /* Base address of a memory region for I/O */
  size_t  iov_len;  /* Size of memory region                   */
@};
@end example

@subheading Return Value

On successful completion the function returns the number of bytes read.
Otherwise, a value of -1 is returned and @code{errno} is set appropriately.

@table @samp

@item EINVAL
One of the following conditions is true:

@itemize @bullet
@item
The total length to read could overflow a @code{ssize_t}.
@item
@var{iovcnt} was negative, zero or larger than @code{IOV_MAX}.
@end itemize

@end table

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable

@c -----------------------------------------------------------------------------
@node realloc, realpath, readv, Alphabetical List
@unnumberedsec realloc
@c From file ./ansi/stdlib/nmalloc.txh
@subheading Syntax

@example
#include <stdlib.h>

void *realloc(void *ptr, size_t size);
@end example

@subheading Description

This function changes the size of the region pointed to by
@var{ptr}. If it can, it will reuse the same memory space, but
it may have to allocate a new memory space to satisfy the
request.  In either case, it will return the pointer that you
should use to refer to the (possibly new) memory area.  The
pointer passed may be @code{NULL}, in which case this function
acts just like @code{malloc} (@pxref{malloc}).

An application that wants to be robust in the face of a possible
failure of @code{realloc} to enlarge a buffer should save a copy
of the old pointer in a local variable, to be able to use the
original buffer in case @code{realloc} returns @code{NULL}.  See
the example below for details.

Note: excessively large requests are rejected.  At present
excessively large means over @code{INT_MAX} - 65536.

@subheading Return Value

On success, a pointer is returned to the memory you should now
refer to.  On failure, @code{NULL} is returned and the memory
pointed to by @var{ptr} prior to the call is not freed.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
if (now + new > max)
@{
  char *old = p;

  oldmax = max;
  max = now + new;
  p = realloc(p, max);
  if (p == NULL) @{
    p = old;  /* retain the old pointer */
    max = oldmax;
  @}
@}
@end example


@c -----------------------------------------------------------------------------
@node realpath, redir_cmdline_delete, realloc, Alphabetical List
@unnumberedsec realpath
@c From file ./posix/stdlib/realpath.txh
@findex realpath
@subheading Syntax

@example
#include <stdlib.h>

char *realpath(const char *in_path, char *out_path);
@end example

@subheading Description

This function canonicalizes the input path @var{in_path} and stores the
result in the buffer pointed to by @var{out_path}.

The path is canonicialized by removing consecutive and trailing slashes,
making the path absolute if it's relative by prepending the current drive
letter and working directory, removing "." components, collapsing
".." components, adding a drive specifier if needed, and converting all
slashes to '/'.  DOS-style 8+3 names of directories which are part of
the pathname, as well as its final filename part, are returned
lower-cased in @var{out_path}, but long filenames are left intact.
@xref{_preserve_fncase}, for more details on letter-case conversions in
filenames.

Since the returned path name can be longer than the original one, the
caller should ensure there is enough space in the buffer pointed to by
@var{out_path}.  Use of ANSI-standard constant @code{FILENAME_MAX}
(defined on @file{stdio.h}) or Posix-standard constant @code{PATH_MAX}
(defined on @file{limits.h}) is recommended.

If @var{out_path} is specified as @code{NULL}, then @code{realpath} uses
@code{malloc} (@pxref{malloc}) to allocate a buffer of up to @code{PATH_MAX}
bytes to hold the resolved path name, and returns a pointer to this buffer.
The caller should deallocate this buffer using @code{free} (@pxref{free}).

@subheading Return Value

If successful, a pointer to the result buffer is returned. Otherwise,
@code{NULL} is returned and @code{errno} is set to indicate which error
was detected.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
char oldpath[100], newpath[PATH_MAX];
scanf("%s", oldpath);
realpath(oldpath, newpath);
printf("that really is %s\n", newpath);
@end example

@c -----------------------------------------------------------------------------
@node redir_cmdline_delete, redir_cmdline_parse, realpath, Alphabetical List
@unnumberedsec redir_cmdline_delete
@c From file ./debug.txh
@findex redir_cmdline_delete

@subheading Syntax

@example
#include <debug/redir.h>

void redir_cmdline_delete (cmdline_t *cmd);
@end example

@subheading Description

For the rationale and general description of the debugger redirection
issue, see @ref{redir_debug_init}.

This function serves as a destructor for a @code{cmdline_t} object.  It
frees storage used for the command-line arguments associated with
@var{cmd}, closes any open handles stored in it, and frees memory used
to store the file handles and the file names of the files where standard
handles were redirected.

The function is safe to use even if @var{cmd} might be a @code{NULL}
pointer, or if some of members of the @code{cmdline_t} structure are
@code{NULL} pointers.  @xref{redir_debug_init}, for detailed description
of the @code{cmdline_t} structure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
 redir_cmdline_delete (&child_cmd);
@end example


@c -----------------------------------------------------------------------------
@node redir_cmdline_parse, redir_debug_init, redir_cmdline_delete, Alphabetical List
@unnumberedsec redir_cmdline_parse
@c From file ./debug.txh
@findex redir_cmdline_parse

@subheading Syntax

@example
#include <debug/redir.h>

int  redir_cmdline_parse (const char *args, cmdline_t *cmd);
@end example

@subheading Description

For the rationale and general description of the debugger redirection
issue, see @ref{redir_debug_init}.

This function parses a command-line tail (i.e., without the program to
be invoked) passed as a string in @var{args}.  For every redirection
directive in @var{args}, like @samp{>> foo}, it opens the file that is
the target of the redirection, and records in @var{cmd} the information
about these redirections.  (@xref{redir_debug_init}, for details of the
@code{cmdline_t} structure that is used to hold this information.)  The
command line with redirections removed is placed into
@code{cmd->command} (typically, it will be used to call
@code{v2loadimage}, @pxref{v2loadimage}), while the rest of information
is used by @code{redir_to_child} and @code{redir_to_debugger} to
redirect standard handles before and after calling @code{run_child}.

@subheading Return Value

The function returns zero in case of success, -1 otherwise.  Failure
usually means some kind of syntax error, like @samp{>} without a file
name following it; or a file name that isn't allowed by the underlying
OS, like @file{lost+found} on DOS.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  /* Init command line storage.  */
  if (redir_debug_init (&child_cmd) == -1)
    fatal ("Cannot allocate redirection storage: not enough memory.\n");

  /* Parse the command line and create redirections.  */
  if (strpbrk (args, "<>"))
    @{
      if (redir_cmdline_parse (args, &child_cmd) == 0)
	args = child_cmd.command;
      else
	error ("Syntax error in command line.");
    @}
  else
    child_cmd.command = strdup (args);

  cmdline = (char *) alloca (strlen (args) + 4);
  cmdline[0] = strlen (args);
  strcpy (cmdline + 1, args);
  cmdline[strlen (args) + 1] = 13;

  if (v2loadimage (exec_file, cmdline, start_state))
    @{
      printf ("Load failed for image %s\n", exec_file);
      exit (1);
    @}
@end example


@c -----------------------------------------------------------------------------
@node redir_debug_init, redir_to_child, redir_cmdline_parse, Alphabetical List
@unnumberedsec redir_debug_init
@c From file ./debug.txh
@findex redir_debug_init
@tindex dbg_redirect@r{ structure}
@tindex cmdline_t@r{ type}

@subheading Syntax

@example
#include <debug/redir.h>

int redir_debug_init (cmdline_t *cmd);
@end example

@subheading Description

This function initializes the data structure in the @var{cmd} variable
required to save and restore debugger's standard handles across
invocations of @code{run_child} (@pxref{run_child}).  The debugger will
then typically call @code{redir_to_child} and @code{redir_to_debugger}.

These functions are needed when a debugger wants to redirect standard
handles of the debuggee, or if the debuggee redirects some of its
standard handles, because the debuggee is not a separate process, we
just pretend it is by jumping between two threads of execution.  But, as
far as DOS is concerned, the debugger and the debuggee are a single
process, and they share the same @dfn{Job File Table} (JFT).  The JFT is
a table maintained by DOS in the program's PSP where, for each open
handle, DOS stores the index into the SFT, the @dfn{System File Table}.
(The SFT is an internal data structure where DOS maintains everything it
knows about a certain open file/device.)  A handle that is returned by
@code{open}, @code{_open} and other similar functions is simply an index
into the JFT where DOS stored the SFT entry index for the file or device
that the program opened.

When a program starts, the first 5 entries in the JFT are preconnected
to the standard devices.  Any additional handles opened by either the
debugger or the debuggee use handles beyond the first 5 (unless one of
the preconnected handles is deliberately closed).  Here we mostly deal
with handles 0, 1 and 2, the standard input, standard output, and
standard error; they all start connected to the console device (unless
somebody redirects the debugger's I/O from the command line).

Since both the debugger and the debuggee share the same JFT, their
handles 0, 1 and 2 point to the same JFT entries and thus are connected
to the same files/devices.  Therefore, if the debugger redirects its
standard output, the standard output of the debuggee is also
automagically redirected to the same file/device!  Similarly, if the
debuggee redirects its stdout to a file, you won't be able to see
debugger's output (it will go to the same file where the debuggee has
its output); and if the debuggee closes its standard input, you will
lose the ability to talk to debugger!

The debugger redirection support attempts to solve all these problems by
creating an illusion of two separate sets of standard handles.  Each
time the debuggee is about to be run or resumed, it should call
@code{redir_to_child} to redirect debugger's own standard handles to the
file specified in the command-line (as given by e.g. the "run" command
of GDB) before running the debuggee, then call @code{redir_to_debugger}
to redirect them back to the debugger's original input/output when the
control is returned from the debuggee (e.g. after a breakpoint is hit).
Although the debugger and the debuggee have two separate copies of the
file-associated data structures, the debugger still can redirect
standard handles of the debuggee because they use the same JFT entries
as debugger's own standard handles.

The @code{cmdline_t} structure is declared in the header
@file{debug/redir.h} as follows:

@example
struct dbg_redirect @{
  int inf_handle;   /* debuggee's handle */
  int our_handle;   /* debugger's handle */
  char *file_name;  /* file name where debuggee's handle is
                     * redirected */
  int mode;         /* mode used to open() the above file */
  off_t filepos;    /* file position of debuggee's handle; unused */
@};

typedef struct _cmdline @{
  char *command;		    /* command line with redirection removed */
  int redirected;		    /* 1 if handles redirected for child */
  struct dbg_redirect **redirection;/* info about redirected handles */
@} cmdline_t;
@end example

In the @code{cmdline_t} structure, the @code{redirection} member points
to an array of 3 @code{dbg_redirect} structures, one each for each one
of the 3 standard handles.  The @code{inf_handle} and @code{our_handle}
members of those structures are used to save the handle used,
respectively, by the debuggee (a.k.a.@: @dfn{the inferior process}) and
by the debugger.

The @var{cmd} variable is supposed to be defined by the debugger's
application code.  @code{redir_debug_init} is called to initialize that
variable.  It calls @code{redir_cmdline_delete} to close any open
handles held in @var{cmd} and to free any allocated storage; then it
fills @var{cmd} with the trivial information (i.e., every standard
stream is connected to the usual handles 0, 1, and 2).

@subheading Return Value

@code{redir_debug_init} returns zero in case of success, or -1
otherwise.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
 if (redir_debug_init (&child_cmd) == -1)
   fatal ("Cannot allocate redirection storage: not enough memory.\n");
@end example


@c -----------------------------------------------------------------------------
@node redir_to_child, redir_to_debugger, redir_debug_init, Alphabetical List
@unnumberedsec redir_to_child
@c From file ./debug.txh
@findex redir_to_child

@subheading Syntax

@example
#include <debug/redir.h>

int redir_to_child (cmdline_t *cmd);
@end example

@subheading Description

For the rationale and general description of the debugger redirection
issue, see @ref{redir_debug_init}.

This function redirects all 3 standard streams so that they point to the
files/devices where the child (a.k.a.@: debuggee) process connected
them.  All three standard handles point to the console device by
default, but this could be changed, either because the command line for
the child requested redirection, like in @samp{prog > foo}, or because
the child program itself redirected one of its standard handles
e.g. with a call to @code{dup2}.

@code{redir_to_child} uses information stored in the @code{cmdline_t}
variable pointed to by the @var{cmd} argument to redirect the standard
streams as appropriate for the debuggee, while saving the original
debugger's handles to be restored by @code{redir_to_debugger}.

@subheading Return Value

The function returns zero in case of success, -1 in case of failure.
Failure usually means the process has run out of available file
handles.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  errno = 0;
  if (redir_to_child (&child_cmd) == -1)
    @{
      redir_to_debugger (&child_cmd);
      error ("Cannot redirect standard handles for program: %s.",
             strerror (errno));
    @}
@end example


@c -----------------------------------------------------------------------------
@node redir_to_debugger, regcomp, redir_to_child, Alphabetical List
@unnumberedsec redir_to_debugger
@c From file ./debug.txh
@findex redir_to_debugger

@subheading Syntax

@example
#include <debug/redir.h>

int redir_to_debugger (cmdline_t *cmd);
@end example

@subheading Description

For the rationale and general description of the debugger redirection
issue, see @ref{redir_debug_init}.

This function redirects all 3 standard streams so that they point to the
files/devices where the debugger process connected them.  All three
standard handles point to the console device by default, but this could
be changed, either because the command line for the child requested
redirection, like in @samp{prog > foo}, or because the child program
itself redirected one of its standard handles e.g. with a call to
@code{dup2}.

@code{redir_to_debugger} uses information stored in the @code{cmdline_t}
variable pointed to by the @var{cmd} argument to redirect the standard
streams as appropriate for the debugger, while saving the original
debuggee's handles to be restored by @code{redir_to_child}.

@subheading Return Value

The function returns zero in case of success, -1 in case of failure.
Failure usually means the process has run out of available file
handles.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
 /* Restore debugger's standard handles.  */
 errno = 0;
 if (redir_to_debugger (&child_cmd) == -1)
   error ("Cannot redirect standard handles for debugger: %s.",
          strerror (errno));
@end example



@c -----------------------------------------------------------------------------
@node regcomp, regerror, redir_to_debugger, Alphabetical List
@unnumberedsec regcomp
@c From file ./posix/regex/regex.txh
@findex regcomp
@tindex regex_t@r{ type}
@subheading Syntax

@example
#include <sys/types.h>
#include <regex.h>

int regcomp(regex_t *preg, const char *pattern, int cflags);
@end example

@subheading Description

This function is part of the implementation of @sc{posix 1003.2} regular
expressions (@dfn{RE}s).

@code{regcomp} compiles the regular expression contained in the
@var{pattern} string, subject to the flags in @var{cflags}, and places
the results in the @code{regex_t} structure pointed to by @var{preg}.
(The regular expression syntax, as defined by @sc{posix 1003.2}, is
described below.)

The parameter @var{cflags} is the bitwise OR of zero or more of the
following flags:

@table @code

@item REG_EXTENDED

Compile modern (@dfn{extended}) REs, rather than the obsolete
(@dfn{basic}) REs that are the default.

@item REG_BASIC

This is a synonym for 0, provided as a counterpart to
@code{REG_EXTENDED} to improve readability.
This is an extension, compatible with but not specified by
@sc{posix 1003.2}, and should be used with caution in software
intended to be portable to other systems.

@item REG_NOSPEC

Compile with recognition of all special characters turned off.  All
characters are thus considered ordinary, so the RE in @var{pattern} is a
literal string.  This is an extension, compatible with but not specified
by @sc{posix 1003.2}, and should be used with caution in software
intended to be portable to other systems.  @code{REG_EXTENDED} and
@code{REG_NOSPEC} may not be used in the same call to @code{regcomp}.

@item REG_ICASE

Compile for matching that ignores upper/lower case distinctions.  See
the description of regular expressions below for details of
case-independent matching.

@item REG_NOSUB

Compile for matching that need only report success or failure, not what
was matched.

@item REG_NEWLINE

Compile for newline-sensitive matching.  By default, newline is a
completely ordinary character with no special meaning in either REs or
strings.  With this flag, @samp{[^} bracket expressions and @samp{.}
never match newline, a @samp{^} anchor matches the null string after any
newline in the string in addition to its normal function, and the
@samp{$} anchor matches the null string before any newline in the string
in addition to its normal function.

@item REG_PEND

The regular expression ends, not at the first NUL, but just before the
character pointed to by the @code{re_endp} member of the structure
pointed to by @var{preg}.  The @code{re_endp} member is of type
@code{const char *}.  This flag permits inclusion of NULs in the RE;
they are considered ordinary characters.  This is an extension,
compatible with but not specified by @sc{posix 1003.2}, and should be
used with caution in software intended to be portable to other systems.

@end table

When successful, @code{regcomp} returns 0 and fills in the structure
pointed to by @var{preg}.  One member of that structure (other than
@code{re_endp}) is publicized: @code{re_nsub}, of type @code{size_t},
contains the number of parenthesized subexpressions within the RE
(except that the value of this member is undefined if the
@code{REG_NOSUB} flag was used).

Note that the length of the RE does matter; in particular, there is a
strong speed bonus for keeping RE length under about 30 characters,
with most special characters counting roughly double.

@subheading Return Value

If @code{regcomp} succeeds, it returns zero; if it fails, it returns a
non-zero error code, which is one of these:

@table @code

@item REG_BADPAT

invalid regular expression

@item REG_ECOLLATE

invalid collating element

@item REG_ECTYPE

invalid character class

@item REG_EESCAPE

@samp{\} applied to unescapable character

@item REG_ESUBREG

invalid backreference number (e.g., larger than the number of
parenthesized subexpressions in the RE)

@item REG_EBRACK

brackets [ ] not balanced

@item REG_EPAREN

parentheses ( ) not balanced

@item REG_EBRACE

braces @{ @} not balanced

@item REG_BADBR

invalid repetition count(s) in @{ @}

@item REG_ERANGE

invalid character range in [ ]

@item REG_ESPACE

ran out of memory (an RE like, say,
@samp{((((a@{1,100@})@{1,100@})@{1,100@})@{1,100@})@{1,100@}'} will
eventually run almost any existing machine out of swap space)

@item REG_BADRPT

?, *, or + operand invalid

@item REG_EMPTY

empty (sub)expression

@item REG_ASSERT

``can't happen'' (you found a bug in @code{regcomp})

@item REG_INVARG

invalid argument (e.g. a negative-length string)

@end table

@subheading Regular Expressions' Syntax

Regular expressions (@dfn{RE}s), as defined in @sc{posix 1003.2}, come
in two forms: modern REs (roughly those of @code{egrep}; 1003.2 calls
these @emph{extended} REs) and obsolete REs (roughly those of @code{ed};
1003.2 @emph{basic} REs).  Obsolete REs mostly exist for backward
compatibility in some old programs; they will be discussed at the end.
1003.2 leaves some aspects of RE syntax and semantics open; `(*)' marks
decisions on these aspects that may not be fully portable to other
1003.2 implementations.

A (modern) RE is one(*) or more non-empty(*) @emph{branches}, separated
by @samp{|}.  It matches anything that matches one of the branches.

A branch is one(*) or more @emph{pieces}, concatenated.  It matches a
match for the first, followed by a match for the second, etc.

A piece is an @emph{atom} possibly followed by a single(*) @samp{*},
@samp{+}, @samp{?}, or @emph{bound}.  An atom followed by @samp{*}
matches a sequence of 0 or more matches of the atom.  An atom followed
by @samp{+} matches a sequence of 1 or more matches of the atom.  An
atom followed by @samp{?} matches a sequence of 0 or 1 matches of the
atom.

A @emph{bound} is @samp{@{} followed by an unsigned decimal integer,
possibly followed by @samp{,} possibly followed by another unsigned
decimal integer, always followed by @samp{@}}.  The integers must lie
between 0 and @code{RE_DUP_MAX} (255(*)) inclusive, and if there are two
of them, the first may not exceed the second.  An atom followed by a
bound containing one integer @samp{i} and no comma matches a sequence of
exactly @samp{i} matches of the atom.  An atom followed by a bound
containing one integer @samp{i} and a comma matches a sequence of
@samp{i} or more matches of the atom.  An atom followed by a bound
containing two integers @samp{i} and @samp{j} matches a sequence of
@samp{i} through @samp{j} (inclusive) matches of the atom.

An atom is a regular expression enclosed in @samp{()} (matching a match
for the regular expression), an empty set of @samp{()} (matching the
null string(*)), a @emph{bracket expression} (see below), @samp{.}
(matching any single character), @samp{^} (matching the null string at
the beginning of a line), @samp{$} (matching the null string at the end
of a line), a @samp{\} followed by one of the characters
@samp{^.[$()|*+?@{\\} (matching that character taken as an ordinary
character), a @samp{\} followed by any other character(*) (matching
that character taken as an ordinary character, as if the @samp{\} had
not been present(*)), or a single character with no other significance
(matching that character).  A @samp{@{} followed by a character other
than a digit is an ordinary character, not the beginning of a bound(*).
It is illegal to end an RE with @samp{\}.

A @emph{bracket expression} is a list of characters enclosed in
@samp{[]}.  It normally matches any single character from the list (but
see below).  If the list begins with @samp{^}, it matches any single
character (but see below) @emph{not} from the rest of the list.  If two
characters in the list are separated by @samp{-}, this is shorthand for
the full @emph{range} of characters between those two (inclusive) in the
collating sequence, e.g. @samp{[0-9]} in ASCII matches any decimal
digit.  It is illegal(*) for two ranges to share an endpoint,
e.g. @samp{a-c-e}.  Ranges are very collating-sequence-dependent, and
portable programs should avoid relying on them.

To include a literal @samp{]} in the list, make it the first character
(following a possible @samp{^}).  To include a literal @samp{-}, make it
the first or last character, or the second endpoint of a range.  To use
a literal @samp{-} as the first endpoint of a range, enclose it in
@samp{[.} and @samp{.]} to make it a collating element (see below).
With the exception of these and some combinations using @samp{[} (see
next paragraphs), all other special characters, including @samp{\},
lose their special significance within a bracket expression.

Within a bracket expression, a collating element (a character, a
multi-character sequence that collates as if it were a single character,
or a collating-sequence name for either) enclosed in @samp{[.} and
@samp{.]}  stands for the sequence of characters of that collating
element.  The sequence is a single element of the bracket expression's
list.  A bracket expression containing a multi-character collating
element can thus match more than one character, e.g. if the collating
sequence includes a @samp{ch} collating element, then the RE
@samp{[[.ch.]]*c} matches the first five characters of ``chchcc''.

Within a bracket expression, a collating element enclosed in @samp{[=}
and @samp{=]} is an equivalence class, standing for the sequences of
characters of all collating elements equivalent to that one, including
itself.  (If there are no other equivalent collating elements, the
treatment is as if the enclosing delimiters were @samp{[.} and
@samp{.]}.)  For example, if @samp{o} and @samp{^} are the members of an
equivalence class, then @samp{[[=o=]]}, @samp{[[=^=]]}, and @samp{[o^]}
are all synonymous.  An equivalence class may @emph{not} be an endpoint
of a range.

Within a bracket expression, the name of a @emph{character class}
enclosed in @samp{[:} and @samp{:]} stands for the list of all characters
belonging to that class.
Standard character class names are:

@example
alnum	digit	punct
alpha	graph	space
blank	lower	upper
cntrl	print	xdigit
@end example

These stand for the character classes defined by @code{isalnum}
(@pxref{isalnum}), @code{isdigit} (@pxref{isdigit}), @code{ispunct}
(@pxref{ispunct}), @code{isalpha} (@pxref{isalpha}), @code{isgraph}
(@pxref{isgraph}), @code{isspace} (@pxref{isspace}) (@code{blank} is the
same as @code{space}), @code{islower} (@pxref{islower}), @code{isupper}
(@pxref{isupper}), @code{iscntrl} (@pxref{iscntrl}), @code{isprint}
(@pxref{isprint}), and @code{isxdigit} (@pxref{isxdigit}),
respectively.  A locale may provide others.  A character class may not
be used as an endpoint of a range.

There are two special cases(*) of bracket expressions: the bracket
expressions @samp{[[:<:]]} and @samp{[[:>:]]} match the null string at the
beginning and end of a word respectively.  A word is defined as a
sequence of word characters which is neither preceded nor followed by
word characters.  A word character is an @code{alnum} character (as
defined by @code{isalnum} library function) or an underscore.  This is
an extension, compatible with but not specified by @sc{posix 1003.2},
and should be used with caution in software intended to be portable to
other systems.

In the event that an RE could match more than one substring of a given
string, the RE matches the one starting earliest in the string.  If the
RE could match more than one substring starting at that point, it
matches the longest.  Subexpressions also match the longest possible
substrings, subject to the constraint that the whole match be as long as
possible, with subexpressions starting earlier in the RE taking priority
over ones starting later.  Note that higher-level subexpressions thus
take priority over their lower-level component subexpressions.

Match lengths are measured in characters, not collating elements.  A
null string is considered longer than no match at all.  For example,
@samp{bb*} matches the three middle characters of ``abbbc'', 
@samp{(wee|week)(knights|nights)} matches all ten characters of
``weeknights'', when @samp{(.*).*} is matched against ``abc'' the
parenthesized subexpression matches all three characters, and when
@samp{(a*)*} is matched against ``bc'' both the whole RE and the
parenthesized subexpression match the null string.

If case-independent matching is specified, the effect is much as if all
case distinctions had vanished from the alphabet.  When an alphabetic
that exists in multiple cases appears as an ordinary character outside a
bracket expression, it is effectively transformed into a bracket
expression containing both cases, e.g. @samp{x} becomes @samp{[xX]}.
When it appears inside a bracket expression, all case counterparts of it
are added to the bracket expression, so that (e.g.) @samp{[x]} becomes
@samp{[xX]} and @samp{[^x]} becomes @samp{[^xX]}.

No particular limit is imposed on the length of REs(*).  Programs
intended to be portable should not employ REs longer than 256 bytes,
as an implementation can refuse to accept such REs and remain
@sc{posix}-compliant.

Obsolete (@emph{basic}) regular expressions differ in several respects.
@samp{|}, @samp{+}, and @samp{?} are ordinary characters and there is no
equivalent for their functionality.  The delimiters for bounds are
@samp{\@{} and @samp{\@}}, with @samp{@{} and @samp{@}} by themselves
ordinary characters.  The parentheses for nested subexpressions are
@samp{\(} and @samp{\)}, with @samp{(} and @samp{)} by themselves
ordinary characters.  @samp{^} is an ordinary character except at the
beginning of the RE or(*) the beginning of a parenthesized
subexpression, @samp{$} is an ordinary character except at the end of
the RE or(*) the end of a parenthesized subexpression, and @samp{*} is
an ordinary character if it appears at the beginning of the RE or the
beginning of a parenthesized subexpression (after a possible leading
@samp{^}).  Finally, there is one new type of atom, a @emph{back
reference}: @samp{\} followed by a non-zero decimal digit @emph{d}
matches the same sequence of characters matched by the @emph{d}th
parenthesized subexpression (numbering subexpressions by the positions
of their opening parentheses, left to right), so that (e.g.)
@samp{\([bc]\)\1} matches ``bb'' or ``cc'' but not ``bc''.

@subheading History

This implementation of the @sc{posix} regexp functionality was written
by @email{henry@@zoo.toronto.edu, Henry Spencer}.

@subheading Bugs

The locale is always assumed to be the default one of 1003.2, and only
the collating elements etc. of that locale are available.

@code{regcomp} implements bounded repetitions by macro expansion,
which is costly in time and space if counts are large or bounded
repetitions are nested.

An RE like, say,
@samp{((((a@{1,100@})@{1,100@})@{1,100@})@{1,100@})@{1,100@}},
will (eventually) run almost any existing machine out of swap space.

There are suspected problems with response to obscure error conditions.
Notably, certain kinds of internal overflow, produced only by truly
enormous REs or by multiply nested bounded repetitions, are probably not
handled well.

Due to a mistake in 1003.2, things like @samp{a)b} are legal REs because
@samp{)} is a special character only in the presence of a previous
unmatched @samp{(}.  This can't be fixed until the spec is fixed.

The standard's definition of back references is vague.  For example,
does @samp{a\e(\e(b\e)*\e2\e)*d} match ``abbbd''?  Until the standard
is clarified, behavior in such cases should not be relied on.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable



@c -----------------------------------------------------------------------------
@node regerror, regexec, regcomp, Alphabetical List
@unnumberedsec regerror
@c From file ./posix/regex/regex.txh
@findex regerror
@subheading Syntax

@example

#include <sys/types.h>
#include <regex.h>

size_t regerror(int errcode, const regex_t *preg,
                char *errbuf, size_t errbuf_size);

@end example

@subheading Description

@code{regerror} maps a non-zero value of @var{errcode} from either
@code{regcomp} (Return Value, @pxref{regcomp}) or @code{regexec}
(Return Value, @pxref{regexec}) to a human-readable, printable message.

If @var{preg} is non-@code{NULL}, the error code should have arisen from
use of the variable of the type @code{regex_t} pointed to by @var{preg},
and if the error code came from @code{regcomp}, it should have been the
result from the most recent @code{regcomp} using that @code{regex_t}
variable.  (@code{regerror} may be able to supply a more detailed
message using information from the @code{regex_t} than from
@var{errcode} alone.)  @code{regerror} places the @code{NUL}-terminated
message into the buffer pointed to by @var{errbuf}, limiting the length
(including the @code{NUL}) to at most @var{errbuf_size} bytes.  If the
whole message won't fit, as much of it as will fit before the
terminating @code{NUL} is supplied.  In any case, the returned value is
the size of buffer needed to hold the whole message (including
terminating @code{NUL}).  If @var{errbuf_size} is 0, @var{errbuf} is
ignored but the return value is still correct.

If the @var{errcode} given to @code{regerror} is first ORed with
@code{REG_ITOA}, the ``message'' that results is the printable name of
the error code, e.g. ``REG_NOMATCH'', rather than an explanation
thereof.  If @var{errcode} is @code{REG_ATOI}, then @var{preg} shall be
non-NULL and the @code{re_endp} member of the structure it points to
must point to the printable name of an error code
(e.g. ``REG_ECOLLATE''); in this case, the result in @var{errbuf} is the
decimal representation of the numeric value of the error code (0 if the
name is not recognized).  @code{REG_ITOA} and @code{REG_ATOI} are
intended primarily as debugging facilities; they are extensions,
compatible with but not specified by @sc{posix 1003.2}, and should be
used with caution in software intended to be portable to other systems.
Be warned also that they are considered experimental and changes are
possible.

@subheading Return Value

The size of buffer needed to hold the message (including terminating
@code{NUL}) is always returned, even if @var{errbuf_size} is zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable



@c -----------------------------------------------------------------------------
@node regexec, regfree, regerror, Alphabetical List
@unnumberedsec regexec
@c From file ./posix/regex/regex.txh
@findex regexec
@subheading Syntax

@example
#include <sys/types.h>
#include <regex.h>

int regexec(const regex_t *preg, const char *string,
            size_t nmatch, regmatch_t pmatch[], int eflags);
@end example


@subheading Description

@code{regexec} matches the compiled RE pointed to by @var{preg} against
the @var{string}, subject to the flags in @var{eflags}, and reports
results using @var{nmatch}, @var{pmatch}, and the returned value.  The
RE must have been compiled by a previous invocation of @code{regcomp}
(@pxref{regcomp}).  The compiled form is not altered during execution of
@code{regexec}, so a single compiled RE can be used simultaneously by
multiple threads.

By default, the NUL-terminated string pointed to by @var{string} is
considered to be the text of an entire line, with the NUL indicating the
end of the line.  (That is, any other end-of-line marker is considered
to have been removed and replaced by the NUL.)

The @var{eflags} argument is the bitwise OR of zero or more of the
following flags:

@table @code

@item REG_NOTBOL

The first character of the string is not the beginning of a line, so the
@samp{^} anchor should not match before it.  This does not affect the
behavior of newlines under @code{REG_NEWLINE} (REG_NEWLINE,
@pxref{regcomp}).

@item REG_NOTEOL

The NUL terminating the string does not end a line, so the @samp{$} anchor
should not match before it.  This does not affect the behavior of
newlines under @code{REG_NEWLINE} (REG_NEWLINE, @pxref{regcomp}).

@item REG_STARTEND

The string is considered to start at
@w{@code{@var{string} + @var{pmatch}[0].rm_so}}
and to have a terminating @code{NUL} located at
@w{@code{@var{string} + @var{pmatch}[0].rm_eo}} (there need not actually
be a @code{NUL} at that location), regardless of the value of @var{nmatch}.
See below for the definition of @var{pmatch} and @var{nmatch}.  This is
an extension, compatible with but not specified by @sc{posix 1003.2},
and should be used with caution in software intended to be portable to
other systems.  Note that a non-zero @code{rm_so} does not imply
@code{REG_NOTBOL}; @code{REG_STARTEND} affects only the location of the
string, not how it is matched.

@item REG_TRACE

trace execution (printed to stdout)

@item REG_LARGE

force large representation

@item REG_BACKR

force use of backref code

@end table

Regular Expressions' Syntax, @xref{regcomp}, for a discussion of what is
matched in situations where an RE or a portion thereof could match any
of several substrings of @var{string}.

If @code{REG_NOSUB} was specified in the compilation of the RE
(REG_NOSUB, @pxref{regcomp}), or if @var{nmatch} is 0, @code{regexec}
ignores the @var{pmatch} argument (but see below for the case where
@code{REG_STARTEND} is specified).  Otherwise, @var{pmatch} should point
to an array of @var{nmatch} structures of type @code{regmatch_t}.  Such
a structure has at least the members @code{rm_so} and @code{rm_eo}, both
of type @code{regoff_t} (a signed arithmetic type at least as large as
an @code{off_t} and a @code{ssize_t}), containing respectively the offset
of the first character of a substring and the offset of the first
character after the end of the substring.  Offsets are measured from the
beginning of the @var{string} argument given to @code{regexec}.  An
empty substring is denoted by equal offsets, both indicating the
character following the empty substring.

When @code{regexec} returns, the 0th member of the @var{pmatch} array is
filled in to indicate what substring of @var{string} was matched by the
entire RE.  Remaining members report what substring was matched by
parenthesized subexpressions within the RE; member @code{i} reports
subexpression @code{i}, with subexpressions counted (starting at 1) by
the order of their opening parentheses in the RE, left to right.  Unused
entries in the array---corresponding either to subexpressions that did
not participate in the match at all, or to subexpressions that do not
exist in the RE (that is, @code{@w{i > preg->re_nsub}})---have both
@code{rm_so} and @code{rm_eo} set to @code{-1}.  If a subexpression
participated in the match several times, the reported substring is the
last one it matched.  (Note, as an example in particular, that when the
RE @samp{(b*)+} matches ``bbb'', the parenthesized subexpression
matches the three @samp{b}s and then an infinite number of empty
strings following the last @samp{b}, so the reported substring is one of the
empties.)

If @code{REG_STARTEND} is specified in @var{eflags}, @var{pmatch} must
point to at least one @code{regmatch_t} variable (even if @var{nmatch}
is 0 or @code{REG_NOSUB} was specified in the compilation of the RE,
REG_NOSUB, @pxref{regcomp}), to hold the input offsets for
@code{REG_STARTEND}.  Use for output is still entirely controlled by
@var{nmatch}; if @var{nmatch} is 0 or @code{REG_NOSUB} was specified,
the value of @code{pmatch[0]} will not be changed by a successful
@code{regexec}.

@subheading Return Value

Normally, @code{regexec} returns 0 for success and the non-zero code
@code{REG_NOMATCH} for failure.  Other non-zero error codes may be
returned in exceptional situations.  The list of possible error return
values is below:

@table @code

@item REG_ESPACE

ran out of memory

@item REG_BADPAT

the passed argument @var{preg} doesn't point to an RE compiled by
@code{regcomp}

@item REG_INVARG

invalid argument(s) (e.g.,
@w{@code{@var{string} + @var{pmatch}[0].rm_eo}} is less
than @w{@code{@var{string} + @var{pmatch}[0].rm_so}})

@end table

@subheading History

This implementation of the @sc{posix} regexp functionality was written
by @email{henry@@zoo.toronto.edu, Henry Spencer}.

@subheading Bugs

@code{regexec} performance is poor.  @var{nmatch} exceeding 0 is
expensive; @var{nmatch} exceeding 1 is worse.  @code{regexec} is largely
insensitive to RE complexity @emph{except} that back references are
massively expensive.  RE length does matter; in particular, there is a
strong speed bonus for keeping RE length under about 30 characters, with
most special characters counting roughly double.

The implementation of word-boundary matching is a bit of a kludge, and
bugs may lurk in combinations of word-boundary matching and anchoring.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable



@c -----------------------------------------------------------------------------
@node regfree, remove, regexec, Alphabetical List
@unnumberedsec regfree
@c From file ./posix/regex/regex.txh
@findex regfree
@subheading Syntax

@example

#include <sys/types.h>
#include <regex.h>

void regfree(regex_t *preg);

@end example

@subheading Description

@code{regfree} frees any dynamically-allocated storage associated with
the compiled RE pointed to by @var{preg}.  The remaining @code{regex_t}
is no longer a valid compiled RE and the effect of supplying it to
@code{regexec} or @code{regerror} is undefined.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node remove, remque, regfree, Alphabetical List
@unnumberedsec remove
@c From file ./ansi/stdio/remove.txh
@findex remove
@subheading Syntax

@example
#include <stdio.h>

int remove(const char *file);
@end example

@subheading Description

This function removes the named @var{file} from the file system.  Unless
you have an un-erase program, the file and its contents are gone for
good. 

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
remove("/tmp/data.tmp");
@end example

@c -----------------------------------------------------------------------------
@node remque, _rename, remove, Alphabetical List
@unnumberedsec remque
@c From file ./compat/search/remque.txh
@findex remque
@subheading Syntax

@example
#include <search.h>

void remque(struct qelem *elem);
@end example

@subheading Description

This function manipulates queues built from doubly linked lists.  Each element
in the queue must be in the form of @code{struct qelem} which is defined
thus:

@example
struct qelem @{
  struct qelem *q_forw;
  struct qelem *q_back;
  char q_data[0];
@}
@end example

This function removes the entry @var{elem} from a queue.

@subheading Return Value

None.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _rename, rename, remque, Alphabetical List
@unnumberedsec _rename
@c From file ./ansi/stdio/rename.txh
@findex _rename
@vindex LFN@r{ environment variable and }_rename
@subheading Syntax

@example
#include <stdio.h>

int _rename(const char *oldname, const char *newname);
@end example

@subheading Description

This function renames an existing file or directory @var{oldname} to
@var{newname}.  It is much smaller that @code{rename} (@pxref{rename}),
but it can only rename a directory so it stays under the same parent, it
cannot move directories between different branches of the directory
tree.  This means that in the following example, the first call will
succeed, while the second will fail:

@example
_rename("c:/path1/mydir", "c:/path1/yourdir");
_rename("c:/path1/mydir", "c:/path2");
@end example

On systems that support long filenames (@pxref{_use_lfn}),
@code{_rename} can also move directories (so that both calls in the
above example succeed there), unless the @samp{LFN} environment variable
is set to @kbd{n}, or the @code{_CRT0_FLAG_NO_LFN} is set in the
@code{_crt0_startup_flags} variable, @xref{_crt0_startup_flags}.

If you don't need the extra functionality offered by @code{rename}
(which usually is only expected by Unix-born programs), you can use
@code{_rename} instead and thus make your program a lot smaller.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node rename, rewind, _rename, Alphabetical List
@unnumberedsec rename
@c From file ./ansi/stdio/rename.txh
@findex rename
@subheading Syntax

@example
#include <stdio.h>

int rename(const char *oldname, const char *newname);
@end example

@subheading Description

This function renames an existing file or directory @var{oldname} to
@var{newname}.  If @var{newname} exists, then it is first removed.  If
@var{newname} is a directory, it must be empty (or else @code{errno} will
be set to @code{ENOTEMPTY}), and must not include @var{oldname} in its
path prefix (otherwise, @code{errno} will be set to @code{EINVAL}).  If
@var{newname} exists, both @var{oldname} and @var{newname} must be of the
same type (both directories or both regular files) (or else @code{errno}
will be set to @code{ENOTDIR} or @code{EISDIR}), and must reside on the
same logical device (otherwise, @code{errno} will be set to @code{EXDEV}). 
Wildcards are not allowed in either @var{oldname} or @var{newname}.  DOS
won't allow renaming a current directory even on a non-default drive (you
will get the @code{EBUSY} or @code{EINVAL} in @code{errno}).
@code{ENAMETOOLONG} will be returned for pathnames which are longer than
the limit imposed by DOS.  If @var{oldname} doesn't exist, @code{errno}
will be set to @code{ENOENT}.  For most of the other calamities, DOS will
usually set @code{errno} to @code{EACCES}.

If anything goes wrong during the operation of @code{rename()}, the
function tries very hard to leave the things as ther were before it was
invoked, but it might not always succeed.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
rename("c:/mydir/some.doc", "c:/yourdir/some.sav");
rename("c:/path1/mydir", "c:/path2");
@end example


@c -----------------------------------------------------------------------------
@node rewind, rewinddir, rename, Alphabetical List
@unnumberedsec rewind
@c From file ./ansi/stdio/rewind.txh
@findex rewind
@subheading Syntax

@example
#include <stdio.h>

void rewind(FILE *file);
@end example

@subheading Description

This function repositions the file pointer to the beginning of the file
and clears the error indicator. 

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
rewind(stdin);
@end example

@c -----------------------------------------------------------------------------
@node rewinddir, rindex, rewind, Alphabetical List
@unnumberedsec rewinddir
@c From file ./posix/dirent/rewinddi.txh
@findex rewinddir
@subheading Syntax

@example
#include <dirent.h>

void rewinddir(DIR *dir);
@end example

@subheading Description

This function resets the position of the @var{dir} so that the next call
to @code{readdir} (@pxref{readdir}) starts at the beginning again. 

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
DIR *d = opendir(".");
rewinddir(d);
@end example

@c -----------------------------------------------------------------------------
@node rindex, rmdir, rewinddir, Alphabetical List
@unnumberedsec rindex
@c From file ./compat/bsd/rindex.txh
@findex rindex
@subheading Syntax

@example
#include <strings.h>

char *rindex(const char *string, int ch);
@end example

@subheading Description

Returns a pointer to the last occurrence of @var{ch} in @var{string}. 
Note that the @code{NULL} character counts, so if you pass zero as
@var{ch} you'll get a pointer to the end of the string back. 

@subheading Return Value

A pointer to the character, or @code{NULL} if it wasn't found.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char *last_slash = rindex(filename, '/');
@end example

@c -----------------------------------------------------------------------------
@node rmdir, run_child, rindex, Alphabetical List
@unnumberedsec rmdir
@c From file ./posix/unistd/rmdir.txh
@findex rmdir
@subheading Syntax

@example
#include <unistd.h>

int rmdir(const char *dirname);
@end example

@subheading Description

This function removes directory @var{dirname}.  The directory must be
empty. 

@subheading Return Value

Zero if the directory was removed, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
rmdir("/tmp/datadir");
@end example


@c -----------------------------------------------------------------------------
@node run_child, save_npx, rmdir, Alphabetical List
@unnumberedsec run_child
@c From file ./debug.txh
@findex run_child
@tindex TSS@r{ structure}
@tindex TSS@r{ type}

@subheading Syntax

@example
#include <debug/dbgcom.h>

void run_child (void);
@end example

@subheading Description

This function starts or resumes the debugged program, via a
@code{longjmp} to the debuggee's code.  When the debuggee hits a
breakpoint, or exits normally, the exception handler that is called to
service the breakpoint exception will @code{longjmp} back to
@code{run_child}, and it will then return to the caller.

After @code{run_child} returns, the debugger usually examines the
@code{a_tss} variable to find out the reason the debuggee stopped.  The
@code{a_tss} variable is defined by the header @file{debug/tss.h} as
follows:

@example
typedef struct TSS @{
	unsigned short tss_back_link;
	unsigned short res0;
	unsigned long  tss_esp0;
	unsigned short tss_ss0;
	unsigned short res1;
	unsigned long  tss_esp1;
	unsigned short tss_ss1;
	unsigned short res2;
	unsigned long  tss_esp2;
	unsigned short tss_ss2;
	unsigned short res3;
	unsigned long  tss_cr3;

	unsigned long  tss_eip;
	unsigned long  tss_eflags;
	unsigned long  tss_eax;
	unsigned long  tss_ecx;
	unsigned long  tss_edx;
	unsigned long  tss_ebx;
	unsigned long  tss_esp;
	unsigned long  tss_ebp;
	unsigned long  tss_esi;
	unsigned long  tss_edi;
	unsigned short tss_es;
	unsigned short res4;
	unsigned short tss_cs;
	unsigned short res5;
	unsigned short tss_ss;
	unsigned short res6;
	unsigned short tss_ds;
	unsigned short res7;
	unsigned short tss_fs;
	unsigned short res8;
	unsigned short tss_gs;
	unsigned short res9;
	unsigned short tss_ldt;
	unsigned short res10;
	unsigned short tss_trap;
	unsigned char  tss_iomap;
	unsigned char  tss_irqn;
	unsigned long  tss_error;
@} TSS;

extern TSS a_tss;
@end example

See the example below for a typical tests after @code{run_child}
returns.

Note that, generally, you'd need to save the standard handles before
calling @code{run_child} and restore them after it returns.  Otherwise,
if the debuggee redirects one of its standard handles, the corresponding
debugger's standard handle is redirected as well.
@xref{redir_to_child}, and see @ref{redir_to_debugger}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
 save_npx ();
 run_child ();
 load_npx ();

 if (a_tss.tss_irqn == 0x21)
  @{
     status = DEBUGGEE_EXITED;
     exit_code = a_tss.tss_eax & 0xff;
  @}
 else
  @{
     status = DEBUGGEE_GOT_SIGNAL
     if (a_tss.tss_irqn == 0x75)
       signal_number = SIGINT;
     else if (a_tss.tss_irqn == 1 || a_tss.tss_irqn == 3)
       signal_number = SIGTRAP;  /* a breakpoint */
  @}
@end example


@c -----------------------------------------------------------------------------
@node save_npx, sbrk, run_child, Alphabetical List
@unnumberedsec save_npx
@c From file ./debug.txh
@findex save_npx
@tindex NPXREG@r{ type}
@tindex NPX@r{ type}
@subheading Syntax

@example
#include <debug/dbgcom.h>

extern NPX npx;
void save_npx (void);
@end example

@subheading Description

This function saves the state of the x87 numeric processor in the
external variable @code{npx}.  This variable is a structure defined as
follows in the header @file{debug/dbgcom.h}:

@example
typedef struct @{
  unsigned short sig0;
  unsigned short sig1;
  unsigned short sig2;
  unsigned short sig3;
  unsigned short exponent:15;
  unsigned short sign:1;
@} NPXREG;

typedef struct @{
  unsigned long control;
  unsigned long status;
  unsigned long tag;
  unsigned long eip;
  unsigned long cs;
  unsigned long dataptr;
  unsigned long datasel;
  NPXREG reg[8];
  long double st[8];
  char st_valid[8];
  long double mmx[8];
  char in_mmx_mode;
  char top;
@} NPX;
@end example


@code{save_npx} should be called immediately before @code{run_child}
(@pxref{run_child}) is called to begin or resume the debugged program.

To restore the x87 state when control is returned to the debugger, call
@code{load_npx}, see @ref{load_npx}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
 save_npx ();
 run_child ();
 load_npx ();
@end example

@c -----------------------------------------------------------------------------
@node sbrk, scanf, save_npx, Alphabetical List
@unnumberedsec sbrk
@c From file ./crt0/crt0.txh
@findex sbrk
@subheading Syntax

@example
#include <unistd.h>

void *sbrk(int delta)
@end example

@subheading Description

This function changes the "break" of the program by adding @var{delta}
to it.  This is the highest address that your program can access without
causing a violation.  Since the heap is the region under the break, you
can expand the heap (where @code{malloc} gets memory from) by increasing
the break. 

This function is normally accessed only by @code{malloc} (@pxref{malloc}).

@subheading Return Value

The address of the first byte outside of the previous valid address
range, or -1 if no more memory could be accessed.  In other words, a
pointer to the chunk of heap you just allocated, if you had passed a
positive number.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char *buf;
buf = sbrk(1000); /* allocate space */
@end example

@c -----------------------------------------------------------------------------
@node scanf, SCN, sbrk, Alphabetical List
@unnumberedsec scanf
@c From file ./ansi/stdio/scanf.txh
@findex scanf
@subheading Syntax

@example
#include <stdio.h>

int scanf(const char *format, @dots{});
@end example

@subheading Description

This function scans formatted text from @code{stdin} and stores it in
the variables pointed to by the arguments.  @xref{scanf}.

The format string contains regular characters which much match the input
exactly as well as a conversion specifiers, which begin with a percent
symbol.  Any whitespace in the format string matches zero or more of any
whitespace characters in the input.  Thus, a single space may match a
newline and two tabs in the input.  All conversions except @samp{c} and
@samp{[} also skip leading whitespace automatically.
Conversions can be applied to the @var{n}th argument after the format in
the argument list, rather than to the next unused argument.  In this case,
the conversion specifier character @code{%} is replaced by the sequence
@code{%@var{n}$}, where @var{n} is a decimal integer in the range [@code{1}, @code{number of the last argument}].
This feature provides for the definition of format strings that select
arguments in an order appropriate to specific languages.  In format strings
containing the @code{%@var{n}$} form of conversion specifications, it is unspecified
whether numbered arguments in the argument list can be referenced from
the format string more than once.  The format can contain either form of
a conversion specification --- that is, @code{%} or @code{%@var{n}$} ---
but the two forms cannot be mixed within a single format string.  The only
exception to this is that @code{%%} or @code{%*} can be mixed with the
@code{%@var{n}$} form.  When numbered argument specifications are used,
specifying the @var{n}th argument requires that all the leading arguments,
from the first to the (@var{n}-1)th, are pointers.
Each conversion specifier contains the following fields:

@itemize @bullet

@item An asterisk (@samp{*}) which indicates that the input should be
converted according to the conversion spec, but not stored anywhere. 
This allows to describe an input field that is to be skipped.

@item A width specifier, which specifies the maximum number of input
characters to use in the conversion. 

@item A @samp{m} character.  This is used with string conversions, and
relieves the caller of the need to allocate a corresponding buffer to hold
the input: instead, @code{scanf} allocates a buffer of sufficient size, and
assigns the address of this buffer to the corresponding  pointer argument,
which should be a pointer to a @var{char *} variable (this variable does
not need to  be initialized before the call).  The caller should subsequently
free this buffer when it is no longer required.  This is a @acronym{GNU} extension.

@item An optional conversion qualifier, which may be:

@table @code
@item hh
to specify @code{char};

@item h
to specify @code{short} integers;

@item j
to specify @code{intmax_t} or @code{uintmax_t} integers;

@item l
to specify doubles or @code{long} integers;

@item ll
(two lower-case ell letters) to specify @code{long long} integers;
to specify @code{long} doubles, although this is non-standard;

@item L
to specify @code{long} doubles;

@item t
to specify @code{ptrdiff_t};

@item z
to specify @code{size_t}.
@end table

If the @samp{h} qualifier appears before a specifier
that implies conversion to a @code{long} or @code{float} or
@code{double}, like in @samp{%hD} or @samp{%hf}, it is generally
ignored.

@item The conversion type specifier@footnote{Some of the combinations
listed below are non-standard.  If you use the non-standard specifiers,
a compiler could complain.}:

@table @code

@item c

Copy the next character (or @var{width} characters) to the given buffer.
This conversion suppresses skipping of the leading whitespace; use
@samp{%1s} to read the next non-whitespace character.  Unlike with
@samp{%s}, the copied characters are @strong{not} terminated with a null
character.  If the @var{width} parameter is not specified, a @var{width}
of one is implied.

@item d

Convert the input to a signed @code{int} using 10 as the base of the
number representation.

@item hhd

Convert the input to a signed @code{char} using 10 as the base.

@item hd

Convert the input to a signed @code{short} using 10 as the base.

@item jd

Convert the input to an @code{intmax_t} using 10 as the base.

@item ld
@itemx D

Convert the input to a signed @code{long} using 10 as the base.

@item Ld
@itemx lld
@itemx lD

Convert the input to a signed @code{long long} using 10 as the base.

@item td

Convert the input to a @code{ptrdiff_t} using 10 as the base.

@item zd

Convert the input to a @code{size_t} using 10 as the base.


@item a
@itemx A

Convert the input of the form [+|-]0xH.HHHHp|P[+|-]DDD to a floating point number (a @code{float}).

@item e
@itemx E
@itemx f
@itemx F
@itemx g
@itemx G

Convert the input to a floating point number (a @code{float}).

@item la
@itemx lA

Convert the input of the form [+|-]0xH.HHHHp|P[+|-]DDD to a floating point number (a @code{double}).

@item le
@itemx lE
@itemx lf
@itemx lF
@itemx lg
@itemx lG

Convert the input to a floating point number (a @code{double}).

@item La
@itemx LA
@item lla
@itemx llA

Convert the input of the form [+|-]0xH.HHHHp|P[+|-]DDD to a floating point number (a @code{double}).

@item Le
@itemx LE
@itemx lle
@itemx llE
@itemx Lf
@itemx LF
@itemx llf
@itemx llF
@itemx Lg
@itemx LG
@itemx llg
@itemx llG

Convert the input to a floating point number (a @code{long double}.

@item i

Convert the input, determining base automatically by the presence of
@code{0x} or @code{0} prefixes, and store in a signed @code{int}.
@xref{strtol}.

@item hhi

Like @samp{i}, but stores the result in a signed @code{char}.

@item hi

Like @samp{i}, but stores the result in a signed @code{short}.

@item ji

Like @samp{i}, but stores the result in an @code{intmax_t}.

@item li
@itemx I

Like @samp{i}, but stores the result in a signed @code{long}.

@item Li
@itemx lli
@itemx lI

Like @samp{i}, but stores the result in a signed @code{long long}.

@item ti

Like @samp{i}, but stores the result in a @code{ptrdiff_t}.

@item zi

Like @samp{i}, but stores the result in a @code{size_t}.

@item n

Store the number of characters scanned so far into the @code{int}
pointed to by the argument.

@item hhn

Like @samp{n}, but the argument should point to a signed @code{char}.

@item hn

Like @samp{n}, but the argument should point to a signed @code{short}.

@item jn

Like @samp{n}, but the argument should point to an @code{intmax_t}.

@item ln

Like @samp{n}, but the argument should point to a signed @code{long}.

@item Ln
@itemx lln

Like @samp{n}, but the argument should point to a signed @code{long long}.

@item tn

Like @samp{n}, but the argument should point to a @code{ptrdiff_t}.

@item zn

Like @samp{n}, but the argument should point to a @code{size_t}.

@item o

Convert the input to an unsigned @code{int}, using base 8.

@item hho

Convert the input to an unsigned @code{char}, using base 8.

@item ho

Convert the input to an unsigned @code{short}, using base 8.

@item jo

Convert the input to an @code{uintmax_t}, using base 8.

@item lo
@itemx O

Convert the input to an unsigned @code{long}, using base 8.

@item Lo
@itemx llo
@itemx lO

Convert the input to an unsigned @code{long long}, using base 8.

@item to

Convert the input to a @code{ptrdiff_t}, using base 8.

@item zo

Convert the input to a @code{size_t}, using base 8.

@item p

Convert the input to a pointer.  This is like using the @code{x} format. 

@item s

Copy the input to the given string, skipping leading whitespace and
copying non-whitespace characters up to the next whitespace.  The string
stored is then terminated with a null character. 

@item u

Convert the input to an unsigned @code{int} using 10 as the base.

@item hhu

Convert the input to an unsigned @code{char} using 10 as the base.

@item hu

Convert the input to an unsigned @code{short} using 10 as the base.

@item ju

Convert the input to an @code{uintmax_t} using 10 as the base.

@item lu
@itemx U

Convert the input to an unsigned @code{long} using 10 as the base.

@item Lu
@itemx llu
@itemx lU

Convert the input to an unsigned @code{long long} using 10 as the base.

@item tu

Convert the input to a @code{ptrdiff_t} using 10 as the base.

@item zu

Convert the input to a @code{size_t} using 10 as the base.

@item x
@itemx X

Convert the input to an unsigned @code{int}, using base 16.

@item hhx
@itemx hhX

Convert the input to an unsigned @code{char}, using base 16.

@item hx
@itemx hX

Convert the input to an unsigned @code{short}, using base 16.

@item jx
@itemx jX

Convert the input to an @code{uintmax_t}, using base 16.

@item lx
@itemx lX

Convert the input to an unsigned @code{long}, using base 16.

@item Lx
@itemx LX
@itemx llx
@itemx llX

Convert the input to an unsigned @code{long long}, using base 16.

@item tx
@itemx tX

Convert the input to a @code{ptrdiff_t}, using base 16.

@item zx
@itemx zX

Convert the input to a @code{size_t}, using base 16.

@item [@dots{}]

Stores the matched characters in a @code{char} array, followed by a
terminating null character.  If you do not specify the @var{width}
parameter, @code{scanf} behaves as if @var{width} had a very large
value.  Up to @var{width} characters are consumed and assigned, provided
that they match the specification inside the brackets.  The characters
between the brackets determine which characters are allowed, and thus
when the copying stops.  These characters may be regular characters
(example: @samp{[abcd]}) or a range of characters (example:
@samp{[a-d]}).  If the first character is a caret (@samp{^}), then the
set specifies the set of characters that do not get copied (i.e.  the
set is negated).  To specify that the set contains a close-bracket
(@samp{]}), put it immediately after @samp{[} or @samp{[^}.  To specify
a literal dash (@samp{-}), write it either immediately after @samp{[} or
@samp{[^}, or immediately before the closing @samp{]}.

@item %

This must match a percent character in the input. 

@end table

@end itemize

Integer formats make use of @code{strtol} or @code{strtoul} to perform
the actual conversions.  Floating-point conversions use @code{strtod}
and @code{_strtold}.

@subheading Return Value

The number of items successfully matched and assigned.  If input ends,
or if there is any input failure before the first item is converted and
assigned, @code{EOF} is returned.  Note that literal characters
(including whitespace) in the format string which matched input
characters count as ``converted items'', so input failure @emph{after}
such characters were read and matched will @strong{not} cause @code{EOF}
to be returned.  If the @code{m} modifier character has been used and
the memory allocation failed, then @var{errno} will be set to @code{ENOMEM}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99 (see note 1); (see note 2)
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 3)
@end multitable

@noindent
Notes:

@enumerate
@item
The @code{hh}, @code{j}, @code{t}
and @code{z} length modifiers and the @code{a}, @code{A}
and @code{F} conversion specifiers first appeared
in the ANSI C99 standard.

@item
The conversion specifiers @samp{F}, @samp{D}, @samp{I},
@samp{O}, and @code{U} are DJGPP extensions; they are provided
for compatibility with Borland C and other compilers.
The conversion specifiers for the @code{long long} data type are
GCC extensions.  The meaning of @samp{[a-c]} as a range of characters
is a very popular extension to ANSI (which merely says a dash
``may have a special meaning'' in that context).

@item
The @code{m} modifier character is a @acronym{GNU}
extension and is specified in the upcoming revision of the @acronym{POSIX.1}
standard.

@end enumerate

@subheading Example

@example
int n, x, y;
char buf[100];
char *buf_ptr, *char_ptr;
char month[9], *source = "december 22, 2012";
int year, day;

scanf("%d %d %s", &x, &y, buf);

/* read to end-of-line */
scanf("%d %[^\n]\n", &x, buf);
/* read letters only */
scanf("%[a-zA-Z]", buf);

/* read 5 charcters and allocate a buffer that is large enough */
scanf("%5mc", &char_ptr);
/* read letters only and allocate a buffer that is large enough */
scanf("%ms", &buf_ptr);

/* read letters only and allocate a buffer that is large enough */
n = scanf("%m[a-z]", &buf_ptr);
if (n == 1)
@{
  printf("read: %s\n", &buf_ptr);
  free(buf_ptr);
@}
else if (errno != 0)
  perror("scanf");
else
  fprintf(stderr, "No matching characters\n"):

/* scan string in sequence: year, month, day */
sscanf(source, "%2$9s %3$d %*[,] %1$d", &year, month, &day);

@end example

@c -----------------------------------------------------------------------------
@node SCN, Screen Variables, scanf, Alphabetical List
@unnumberedsec SCN
@c From file ./c99/inttypes/scn.txh
@subheading Syntax

@example
#include <inttypes.h>
@end example

@subheading Description

The @code{SCN} family of macros allows integers to be input
in a portable manner using the @code{scanf} family of functions
(@pxref{scanf}).  They include a conversion qualifier, to specify
the width of the type (e.g.: @code{l} for @code{long}),
and the conversion type specifier (e.g.: @code{d} for decimal
display of integers).

The @code{SCN} family of macros should be used with the types defined
in the header @code{<stdint.h>}.  For example: @code{int8_t},
@code{uint_fast32_t}, @code{uintptr_t}, @code{intmax_t}.

Below @var{N} can be 8, 16, 32 or 64.  The @code{SCN} macros are:

@table @code

@item SCNd@var{N}
@itemx SCNi@var{N}

The @code{d} and @code{i} type conversion specifiers
for a type @code{int@var{N}_t} of @var{N} bits.

@item SCNdLEAST@var{N}
@itemx SCNiLEAST@var{N}

The @code{d} and @code{i} type conversion specifiers
for a type @code{int_least@var{N}_t} of @var{N} bits.

@item SCNdFAST@var{N}
@itemx SCNiFAST@var{N}

The @code{d} and @code{i} type conversion specifiers
for a type @code{int_fast@var{N}_t} of @var{N} bits.

@item SCNdMAX
@itemx SCNiMAX

The @code{d} and @code{i} type conversion specifiers
for a type @code{intmax_t}.

@item SCNdPTR
@itemx SCNiPTR

The @code{d} and @code{i} type conversion specifier
for a type @code{intptr_t}.

@item SCNo@var{N}
@itemx SCNu@var{N}
@itemx SCNx@var{N}

The @code{o}, @code{u} and @code{x} type conversion specifiers
for a type @code{uint@var{N}_t} of @var{N} bits.

@item SCNoLEAST@var{N}
@itemx SCNuLEAST@var{N}
@itemx SCNxLEAST@var{N}

The @code{o}, @code{u} and @code{x} type conversion specifiers
for a type @code{uint_LEAST@var{N}_t} of @var{N} bits.

@item SCNoFAST@var{N}
@itemx SCNuFAST@var{N}
@itemx SCNxFAST@var{N}

The @code{o}, @code{u} and @code{x} type conversion specifiers
for a type @code{uint_FAST@var{N}_t} of @var{N} bits.

@item SCNoMAX
@itemx SCNuMAX
@itemx SCNxMAX

The @code{o}, @code{u} and @code{x} type conversion specifiers
for a type @code{uintmax_t}.

@item SCNoPTR
@itemx SCNuPTR
@itemx SCNxPTR

The @code{o}, @code{u} and @code{x} type conversion specifiers
for a type @code{uintptr_t}.

@end table

@subheading Return Value

Not applicable.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable


@subheading Example

@example
intmax_t m;
int ret;

ret = sscanf("0x1000", "%" SCNxMAX, &m);
@end example
@c -----------------------------------------------------------------------------
@node Screen Variables, ScreenClear, SCN, Alphabetical List
@unnumberedsec Screen Variables
@c From file ./pc_hw/co80/screen.txh
@vindex ScreenPrimary
@vindex ScreenSecondary
@vindex ScreenAttrib
@subheading Syntax

@example
#include <go32.h>
#include <pc.h>

unsigned long ScreenPrimary;
unsigned long ScreenSecondary;
extern unsigned char ScreenAttrib;

@end example

@subheading Description

The first two variables (actually, they are #define'd aliases to fields in
the @var{_go32_info_block} structure @pxref{_go32_info_block}) allow
access to the video memory of the primary and secondary screens as if they
were arrays.  To reference them, you must use dosmemget()/dosmemput()
functions (@ref{dosmemget}, @pxref{dosmemput}) or any one of the far
pointer functions (@pxref{_far*}), as the video memory is @emph{not} mapped
into your default address space.

The variable ScreenAttrib holds the current attribute which is in use by
the text screen writes.  The attribute is constructed as follows:

bits 0-3  -- foreground color;

bits 4-6  -- background color;

bit  7    -- blink on (1) or off (0).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

_farpokew(_dos_ds, ScreenPrimary, ( ((unsigned short) attr) << 8) + char ));

@example
@end example

@c -----------------------------------------------------------------------------
@node ScreenClear, ScreenCols, Screen Variables, Alphabetical List
@unnumberedsec ScreenClear
@c From file ./pc_hw/co80/screen.txh
@findex ScreenClear
@subheading Syntax

@example
#include <pc.h>

void  ScreenClear(void);

@end example

@subheading Description

This function clears the text screen.  It overwrites it by blanks with the
current background and foreground as specified by ScreenAttrib
(@pxref{Screen Variables}).

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
ScreenClear();
@end example

@c -----------------------------------------------------------------------------
@node ScreenCols, ScreenGetChar, ScreenClear, Alphabetical List
@unnumberedsec ScreenCols
@c From file ./pc_hw/co80/screen.txh
@findex ScreenCols
@subheading Syntax

@example
#include <pc.h>

int ScreenCols(void);

@end example

@subheading Description

This function returns the number of columns of the screen.  It does so by
looking at the byte at the absolute address 40:4Ah in the BIOS area. 
In text modes, the meaning of number of columns is obvious; in graphics
modes, this value is the number of columns of text available when using
the video BIOS functions to write text.

@subheading Return Value

The number of columns.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example

int available_columns = ScreenCols();

@end example

@c -----------------------------------------------------------------------------
@node ScreenGetChar, ScreenGetCursor, ScreenCols, Alphabetical List
@unnumberedsec ScreenGetChar
@c From file ./pc_hw/co80/screen.txh
@findex ScreenGetChar
@subheading Syntax

@example
#include <pc.h>

void  ScreenGetChar(int *ch, int *attr, int col, int row);

@end example

@subheading Description

This function stores the character and attribute of the current
primary screen at row given by @var{row} and column given by @var{col}
(these are zero-based) into the integers whose address is specified by
@var{ch} and @var{attr}.  It does so by directly accessing the video memory,
so it will only work when the screen is in text mode.  You can pass the value
@code{NULL} in each of the pointers if you do not want to retrieve the 
the corresponding information.

@emph{Warning:} note that both the variables @var{ch} and @var{attr} are
pointers to an @code{int}, not to a @code{char}!  You @strong{must} pass
a pointer to an @code{int} there, or your program will crash or work
erratically.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
int ch, attr;

ScreenGetChar(&ch, &attr, 0, 0);
@end example

@c -----------------------------------------------------------------------------
@node ScreenGetCursor, ScreenMode, ScreenGetChar, Alphabetical List
@unnumberedsec ScreenGetCursor
@c From file ./pc_hw/co80/screen.txh
@findex ScreenGetCursor
@subheading Syntax

@example
#include <pc.h>

void  ScreenGetCursor(int *row, int *column);

@end example

@subheading Description

This function retrieves the current cursor position of the default video
page by calling function 3 of the interrupt 10h, and stores it in the
variables pointed by @var{row} and @var{column}.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
ScreenGetCursor(&where_r, &where_c);
@end example

@c -----------------------------------------------------------------------------
@node ScreenMode, ScreenPutChar, ScreenGetCursor, Alphabetical List
@unnumberedsec ScreenMode
@c From file ./pc_hw/co80/screen.txh
@findex ScreenMode
@subheading Syntax

@example
#include <pc.h>

int  ScreenMode(void);


@end example

@subheading Description

This function reports the current video mode as known to the system BIOS.
It does so by accessing the byte at absolute address 40:49h.

@subheading Return Value

The video mode.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
video_mode = ScreenMode();
@end example

@c -----------------------------------------------------------------------------
@node ScreenPutChar, ScreenPutString, ScreenMode, Alphabetical List
@unnumberedsec ScreenPutChar
@c From file ./pc_hw/co80/screen.txh
@findex ScreenPutChar
@subheading Syntax

@example
#include <pc.h>

void  ScreenPutChar(int ch, int attr, int col, int row);

@end example

@subheading Description

This function writes the character whose value is specified in @var{ch}
with an attribute @var{attr} at row given by @var{row} and column given by
@var{col}, which are zero-based.  It does so by directly accessing the
video memory, so it will only work when the screen is in text mode.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
ScreenPutChar('R', (BLUE << 4) | LIGHTMAGENTA, 75, 0);
@end example

@c -----------------------------------------------------------------------------
@node ScreenPutString, ScreenRetrieve, ScreenPutChar, Alphabetical List
@unnumberedsec ScreenPutString
@c From file ./pc_hw/co80/screen.txh
@findex ScreenPutString
@subheading Syntax

@example
#include <pc.h>

void  ScreenPutString(const char *str, int attr, int column, int row);

@end example

@subheading Description

Beginning at screen position given by @var{column} and @var{row}, this
function displays the string given by @var{str}.  Each string character
gets the attribute given by @var{attr}.  If @var{column} or @var{row} have
values outside legal range for current video mode, nothing happens.  The
variables @var{row} and @var{column} are zero-based (e.g., the topmost row
is row 0).

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
ScreenPutString("Hello, world!", (BLUE << 4) | LIGHTBLUE, 20, 10);
@end example

@c -----------------------------------------------------------------------------
@node ScreenRetrieve, ScreenRows, ScreenPutString, Alphabetical List
@unnumberedsec ScreenRetrieve
@c From file ./pc_hw/co80/screen.txh
@findex ScreenRetrieve
@subheading Syntax

@example
#include <pc.h>

void  ScreenRetrieve(void *buf);

@end example

@subheading Description

This function stores a replica of the current primary screen contents in
the buffer pointed to by @var{buf}.  It assumes without checking that
@var{buf} has enough storage to hold the data.  The required storage can
be computed as @code{ScreenRows()*ScreenCols()*2} (@pxref{ScreenRows},
@pxref{ScreenCols}).

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
unsigned *saved_screen = (unsigned *)alloca(ScreenRows()*ScreenCols()*2;

ScreenRetrieve(saved_screen);
@end example

@c -----------------------------------------------------------------------------
@node ScreenRows, ScreenSetCursor, ScreenRetrieve, Alphabetical List
@unnumberedsec ScreenRows
@c From file ./pc_hw/co80/screen.txh
@findex ScreenRows
@subheading Syntax

@example
#include <pc.h>

int ScreenRows(void);

@end example

@subheading Description

This function returns the number of rows of the text screen.  It does so
by looking at the byte at the absolute address 40:84h in the BIOS area.
This method works only for video adapters with their own BIOS extensions,
like EGA, VGA, SVGA etc.

@subheading Return Value

The number of rows.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example

int rows = ScreenRows();

@end example


@c -----------------------------------------------------------------------------
@node ScreenSetCursor, ScreenUpdate, ScreenRows, Alphabetical List
@unnumberedsec ScreenSetCursor
@c From file ./pc_hw/co80/screen.txh
@findex ScreenSetCursor
@subheading Syntax

@example
#include <pc.h>

void  ScreenSetCursor(int  row, int  column);

@end example

@subheading Description

This function moves the cursor position on the default video page to the
point given by (zero-based) @var{row} and @var{column}, by calling
function 2 of interrupt 10h.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
ScreenSetCursor(0, 0);   /* home the cursor */
@end example

@c -----------------------------------------------------------------------------
@node ScreenUpdate, ScreenUpdateLine, ScreenSetCursor, Alphabetical List
@unnumberedsec ScreenUpdate
@c From file ./pc_hw/co80/screen.txh
@findex ScreenUpdate
@subheading Syntax

@example
#include <pc.h>

void  ScreenUpdate(void *buf);

@end example

@subheading Description

This function writes the contents of the buffer @var{buf} to the primary
screen.  The buffer should contain an exact replica of the video memory,
including the characters and their attributes.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
ScreenUpdate(saved_screen);
@end example

@c -----------------------------------------------------------------------------
@node ScreenUpdateLine, ScreenVisualBell, ScreenUpdate, Alphabetical List
@unnumberedsec ScreenUpdateLine
@c From file ./pc_hw/co80/screen.txh
@findex ScreenUpdateLine
@subheading Syntax

@example
#include <pc.h>

void  ScreenUpdateLine(void *buf, int row);

@end example

@subheading Description

This function writes the contents of @var{buf} to the screen line number
given in @var{row} (the topmost line is row 0), on the primary screen.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
ScreenUpdateLine(line_buf, 10);
@end example

@c -----------------------------------------------------------------------------
@node ScreenVisualBell, searchpath, ScreenUpdateLine, Alphabetical List
@unnumberedsec ScreenVisualBell
@c From file ./pc_hw/co80/screen.txh
@findex ScreenVisualBell
@subheading Syntax

@example
#include <pc.h>

void  ScreenVisualBell(void);

@end example

@subheading Description

This function flashes the screen colors to produce the effect of ``visual
bell'.  It does so by momentarily inverting the colors of every character
on the screen.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
ScreenVisualBell();
@end example

@c -----------------------------------------------------------------------------
@node searchpath, seekdir, ScreenVisualBell, Alphabetical List
@unnumberedsec searchpath
@c From file ./dos/dir/srchpath.txh
@findex searchpath
@vindex PATH@r{ environment variable, and finding files with }searchpath
@subheading Syntax
 
@example
#include <dir.h>
 
char * searchpath(const char *file);
@end example
 
@subheading Description
 
Given a name of a file in @var{file}, searches for that file in a list
of directories, including the current working directory and directories
listed in the @code{PATH} environment variable, and if found, returns
the file name with leading directories prepended, so that the result can
be used to access the file (e.g. by calling @code{open} or @code{stat}).

If @var{file} includes a drive letter or leading directories,
@code{searchpath} first tries that name unaltered, in case it is already
a fully-qualified path, or is relative to the current working
directory.  If that fails, it tries every directory in @code{PATH} in
turn.  Note that this will find e.g. @file{c:/foo/bar/baz.exe} if you
pass @samp{bar/baz.exe} to @code{searchpath} and if @file{c:/foo} is
mentioned in @code{PATH}.
 
@subheading Return Value
 
When successfull, the function returns a pointer to a static buffer
where the full pathname of the found file is stored.  Otherwise, it
returns @code{NULL}.  (The static buffer is overwritten on each call.)
 
@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


This function is provided for compatibility with Borland's library.
However, note that the Borland version disregards the leading
directories altogether and searches for the basename only.  Thus, it
will happily find e.g. @file{c:/foo/bar/baz.exe}, even if the directory
@file{c:/foo/bar} doesn't exist, provided that @file{baz.exe} is
somewhere on your @code{PATH}.  We think this is a bug, so DJGPP's
implementation doesn't behave like that.

@subheading Example
 
@example
  printf("%s was found as %s\n", argv[1], searchpath(argv[1]));
 
@end example


@c -----------------------------------------------------------------------------
@node seekdir, select, searchpath, Alphabetical List
@unnumberedsec seekdir
@c From file ./posix/dirent/seekdir.txh
@findex seekdir
@subheading Syntax

@example
#include <dirent.h>

void seekdir(DIR *dir, long loc);
@end example

@subheading Description

This function sets the location pointer in @var{dir} to the specified
@var{loc}.  Note that the value used for @var{loc} should be either zero
or a value returned by @code{telldir} (@pxref{telldir}).  The next call
to @code{readdir} (@pxref{readdir}) will read whatever entry follows that
point in the directory. 

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
int q = telldir(dir);
do_stuff();
seekdir(dir, q);
@end example

@c -----------------------------------------------------------------------------
@node select, __set_fd_flags, seekdir, Alphabetical List
@unnumberedsec select
@c From file ./compat/time/select.txh
@findex select
@subheading Syntax

@example
#include <time.h>
#include <string.h>

int
select(int nfds,
	fd_set *readfds,
	fd_set *writefds,
	fd_set *exceptfds,
	struct timeval *timeout)
@end example

@subheading Description

This function waits for files to be ready for input or output, or to
have exceptional condition pending, or for a timeout.

Each @code{fd_set} variable is a bitmap representation of a set of file
descriptors, one bit for every descriptor.  The following macros shall
be used to deal with these sets (in the table below, @var{p} is a
pointer to an @code{fd_set} object and @var{n} is a file descriptor):

@table @code

@item FD_ZERO(p)

Initialize the set @var{p} to all zeros.

@item FD_SET(n, p)

Set member @var{n} in set @var{p}.

@item FD_CLR(n, p)

Clear member @var{n} in set @var{p}.

@item FD_ISSET(n, p)

Return the value of member @var{n} in set @var{p}.

@item FD_SETSIZE

The maximum number of descriptors supported by the system.

@end table

The @var{nfds} parameter is the number of bits to be examined in each of
the @code{fd_set} sets: the function will only check file descriptors
@code{0} through @code{@var{nfds} - 1}, even if some bits are set for
descriptors beyond that.

On input, some of the bits of each one of the @code{fd_set} sets for
which the function should wait, should be set using the @code{FD_SET}
macro.  @code{select} examines only those descriptors whose bits are
set.

Any of @code{readfds}, @code{writefds}, and @code{exceptfds} can be a
@code{NULL} pointer, if the caller is not interested in testing the
corresponding conditions.

On output, if @code{select} returns a non-negative value, each
non-@code{NULL} argument of the three sets will be replaced with a
subset in which a bit is set for every descriptor that was found to be,
respectively, ready for input, ready for output, and pending an
exceptional condition.  Note that if @code{select} returns -1, meaning a
failure, the descriptor sets are @emph{unchanged}, so you should always
test the return value before looking at the bits in the returned sets.

The @var{timeout} value may be a NULL pointer (no timeout, i.e., wait
forever), a pointer to a zero-value structure (poll mode, i.e., test
once and exit immediately), or a pointer to a @code{struct timeval}
variable (timeout: @code{select} will repeatedly test all the
descriptors until some of them become ready, or the timeout expires).

@code{struct timeval} is defined as follows:

@example
struct timeval @{
  time_t tv_sec;
  long tv_usec;
@};
@end example


@subheading Return Value

On successful return, @code{select} returns the number of files ready,
or 0, if the timeout expired.  The input sets are replaced with subsets
that describe which files are ready for which operations.  If
@code{select} returns 0 (i.e., the timeout has expired), all the
non-@code{NULL} sets have all their bits reset to zero.

On failure, @code{select} returns -1, sets @code{errno} to a suitable
value, and leaves the descriptor sets unchanged.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  struct timeval timeout;
  fd_set read_fds, write_fds;
  int i, select_result;

  timeout.tv_sec = 5;  /* 5-second timeout */
  timeout.tv_usec = 0;

  /* Display status of the 5 files open by default.  */
  for (i = 0; i < 5; i++)
    @{

      FD_ZERO (&read_fds);
      FD_SET (i, &read_fds);
      select_result = select (i + 1, &read_fds, 0, 0, &timeout);
      if (select_result == -1)
        @{
          fprintf(stderr, "%d: Failure for input", i);
          perror("");
        @}
      else
        fprintf(stderr,
                "%d: %s ready for input\n", i,
                select_result ? "" : "NOT");
      FD_ZERO (&write_fds);
      FD_SET (i, &write_fds);
      select_result = select (i + 1, 0, &write_fds, 0, &timeout);
      if (select_result == -1)
        @{
          fprintf(stderr, "%d: Failure for output", i);
          perror("");
        @}
      else
        fprintf(stderr,
                "%d: %s ready for output\n", i,
                select_result ? "" : "NOT");
    @}
@end example

@subheading Implementation Notes

The following notes describe some details pertinent to the DJGPP
implementation of @code{select}:

@itemize @bullet{}
@item
While @code{select} waits for the timeout to expire, it repeatedly calls
the @code{__dpmi_yield} function (@pxref{__dpmi_yield}), so that any
other programs that run at the same time (e.g., on Windows) get more CPU
time.

@item
A file handle that belongs to a @code{FILE} object created by
@code{fopen} or @code{fdopen} (@pxref{fopen}) for which @code{feof} or
@code{ferror} return non-zero, will be reported in the @code{exceptfds}
set; also, such a handle will be reported not input-ready if there are
no pending buffered characters in the @code{FILE} object.  This might be
a feature or a bug, depending on your point of view; in particular, Unix
implementations usually don't check buffered input.  Portable programs
should refrain from mixing @code{select} with buffered I/O.

@item
DOS doesn't support exceptional conditions, so file handles used for
unbuffered I/O will @emph{never} be marked in @code{exceptfds}.

@item
DOS always returns an output-ready indication for a file descriptor
connected to a disk file.  So use of @code{writefds} is only meaningful
for character devices.

@item
The usual text-mode input from the keyboard and other character devices
is line-buffered by DOS.  This means that if you type one character,
@code{select} will indicate that file handle 0 is ready for input, but a
call to @code{getc} will still block until the @key{Enter} key is
pressed.  If you need to make sure that reading a single character won't
block, you should read either with BIOS functions such as @code{getkey}
(@pxref{getkey}) or with raw input DOS functions such as @code{getch}
(@pxref{getch}), or switch the handle to binary mode with a call to
@code{setmode} (@pxref{setmode}).
@end itemize
@c -----------------------------------------------------------------------------
@node __set_fd_flags, __set_fd_properties, select, Alphabetical List
@unnumberedsec __set_fd_flags
@c From file ./dos/io/fd_props.txh
@findex __set_fd_flags
@subheading Syntax

@example
#include <libc/fd_props.h>

void __set_fd_flags(int fd, unsigned long flags);
@end example

@subheading Description

This internal function adds the combination of flags @var{flags} to
the flags associated with the file descriptor @var{fd}.  The flags are
some properties that may be associated with a file descriptor
(@pxref{__set_fd_properties}).

The caller should first check that @var{fd} has properties associated
with it, by calling @code{__has_fd_properties}
(@pxref{__has_fd_properties}).

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node __set_fd_properties, _set_screen_lines, __set_fd_flags, Alphabetical List
@unnumberedsec __set_fd_properties
@c From file ./dos/io/fd_props.txh
@findex __set_fd_properties
@tindex fd_properties@r{ structure}
@cindex fd_props
@cindex fd_properties
@cindex file descriptor properties
@subheading Syntax

@example
#include <libc/fd_props.h>

int __set_fd_properties(int fd, const char *filename, int open_flags);

@end example

@subheading Description

This is an internal function that stores information about the file descriptor
@var{fd} in a @code{fd_properties} struct.  It is called by @code{open} and
its helper functions.

The file name stored in @code{fd_properties} is the result
of the @code{_truename} function (@pxref{_truename}) on @var{filename}.
The @var{open_flags} are scanned and the temporary and append flags
are stored in the @code{flags} field in @code{fd_properties}.

@example
struct fd_properties
@{
  unsigned char ref_count;
  char *filename;
  unsigned long flags;
  fd_properties *prev;
  fd_properties *next;
@};
@end example

@code{flags} can contain a combination of bits:

@table @code

@item FILE_DESC_TEMPORARY
Delete @code{filename} when @code{ref_count} becomes zero.

@item FILE_DESC_ZERO_FILL_EOF_GAP
Tell @code{write} and @code{_write} to test for file offset greater than
EOF.  Set by @code{lseek} and @code{llseek}.

@item FILE_DESC_DONT_FILL_EOF_GAP
Don't test for the EOF gap.  Set automatically for stdin, stdout, and NUL.
Can also be set by an FSEXT.

@item FILE_DESC_PIPE
The file descriptor is used in emulating a pipe.

@item FILE_DESC_APPEND
The file pointer will be set to the end of file before each write.

@item FILE_DESC_DIRECTORY
The file descriptor is for a directory.

@end table

The @code{flags} can be manipulated using
@code{__set_fd_flags} (@pxref{__set_fd_flags}),
@code{__clear_fd_flags} (@pxref{__clear_fd_flags})
and @code{__get_fd_flags} (@pxref{__get_fd_flags}).

The file name can be retrieved using @code{__get_fd_name}
(@pxref{__get_fd_name}).

For more information, see @code{__clear_fd_properties}
(@pxref{__clear_fd_properties}) and @code{__dup_fd_properties}
(@pxref{__dup_fd_properties}).

@subheading Return Value

Returns 0 on success.  Returns -1 when unable to store the information.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _set_screen_lines, setbuf, __set_fd_properties, Alphabetical List
@unnumberedsec _set_screen_lines
@c From file ./pc_hw/co80/conio.txh
@findex _set_screen_lines
@subheading Syntax

@example
#include <conio.h>

void _set_screen_lines(int nlines);
@end example

@subheading Description

This function sets the text screen width to 80 and its height to the
value given by @var{nlines}, which can be one of the following: 25, 28,
35, 40, 43 or 50.  On a CGA, only 25-line screen is supported.  On an
EGA, you can use 25, 35 and 43.  VGA, PGA and MCGA support all of the
possible dimensions.
The number of columns (i.e., screen width) is 80 for all of the above
resolutions, because the standard EGA/VGA has no way of changing it.
After this function returns, calls to @code{gettextinfo()} will return
the actual screen dimensions as set by @code{_set_screen_lines()}.
That is, you can e.g. test whether @code{_set_screen_lines()} succeeded
by checking the screen height returned by @code{gettextinfo()} against
the desired height.
This function has a side effect of erasing the screen contents, so
application programs which use it should make their own arrangements to
redisplay it.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node setbuf, setbuffer, _set_screen_lines, Alphabetical List
@unnumberedsec setbuf
@c From file ./ansi/stdio/setbuf.txh
@findex setbuf
@subheading Syntax

@example
#include <stdio.h>

void setbuf(FILE *file, char *buffer);
@end example

@subheading Description

This function modifies the buffering characteristics of @var{file}. 
First, if the file already has a buffer, it is freed.  If there was any
pending data in it, it is lost, so this function should only be used
immediately after a call to @code{fopen}.

If the @var{buffer} passed is @code{NULL}, the file is set to
unbuffered.  If a non-@code{NULL} buffer is passed, it must be at least
@code{BUFSIZ} bytes in size, and the file is set to fully buffered. 

@xref{setbuffer}.
@xref{setlinebuf}.
@xref{setvbuf}.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
setbuf(stdout, malloc(BUFSIZ));
@end example

@c -----------------------------------------------------------------------------
@node setbuffer, setcbrk, setbuf, Alphabetical List
@unnumberedsec setbuffer
@c From file ./ansi/stdio/setbuffe.txh
@findex setbuffer
@subheading Syntax

@example
#include <stdio.h>

void setbuffer(FILE *file, char *buffer, int length);
@end example

@subheading Description

This function modifies the buffering characteristics of @var{file}. 
First, if the file already has a buffer, it is freed.  If there was any
pending data in it, it is lost, so this function should only be used
immediately after a call to @code{fopen}.

If the @var{buffer} passed is @code{NULL}, the file is set to
unbuffered.  If a non-@code{NULL} buffer is passed, it must be at least
@var{size} bytes in size, and the file is set to fully buffered.

@xref{setbuf}.
@xref{setlinebuf}.
@xref{setvbuf}.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
setbuffer(stdout, malloc(10000), 10000);
@end example

@c -----------------------------------------------------------------------------
@node setcbrk, _setcursortype, setbuffer, Alphabetical List
@unnumberedsec setcbrk
@c From file ./dos/dos/setcbrk.txh
@findex setcbrk
@subheading Syntax

@example
#include <dos.h>

void setcbrk(int check);
@end example

@subheading Description

Set the setting of the Ctrl-Break checking flag in MS-DOS.  If @var{check}
is zero, checking is not done.  If nonzero, checking is done.

@subheading Return Value

None.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node _setcursortype, setdate, setcbrk, Alphabetical List
@unnumberedsec _setcursortype
@c From file ./pc_hw/co80/conio.txh
@findex _setcursortype
@subheading Syntax

@example
#include <conio.h>

void _setcursortype(int _type);
@end example

@subheading Description

Sets the cursor type.  @var{_type} is one of the following:

@table @code

@item _NOCURSOR

No cursor is displayed.

@item _SOLIDCURSOR

A solid block is displayed.

@item _NORMALCURSOR

An underline cursor is displayed.

@end table

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node setdate, setdisk, _setcursortype, Alphabetical List
@unnumberedsec setdate
@c From file ./dos/dos/setdate.txh
@findex setdate
@subheading Syntax

@example
#include <dos.h>

void setdate(struct date *ptr);
@end example

@subheading Description

This function sets the current time.

For the description of @code{struct date}, see @ref{getdate}.  Also see
@ref{settime}.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
struct date d;
setdate(&d);
@end example

@c -----------------------------------------------------------------------------
@node setdisk, setenv, setdate, Alphabetical List
@unnumberedsec setdisk
@c From file ./dos/dir/setdisk.txh
@findex setdisk
@subheading Syntax

@example
#include <dir.h>

int setdisk(int drive);
@end example

@subheading Description

This function sets the current disk (0=A).

See also @ref{getdisk}.

@subheading Return Value

The highest drive actually present that the system can reference.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
printf("There are %d drives\n", setdisk(getdisk()));
@end example

@c -----------------------------------------------------------------------------
@node setenv, setftime, setdisk, Alphabetical List
@unnumberedsec setenv
@c From file ./compat/v1/setenv.txh
@findex setenv
@subheading Syntax

@example
#include <stdlib.h>

int setenv(const char *name, const char *value, int rewrite);
@end example

@subheading Description

This function sets the environment variable @var{name} to @var{value}.
If @var{rewrite} is set, then this function will replace any existing
value.  If it is not set, it will only put the variable into the environment
if that variable isn't already defined.

@subheading Return Value

Zero on success, -1 on failure; @code{errno} is set to the reason for
failure: @code{EINVAL} if the @var{name} parameter is @code{NULL} or points
to an empty string, or @code{ENOMEM} if there was insufficient memory to
add the variable to the environment.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
This function is new to the Posix 1003.1-200x draft.
Our implementation allows @var{name} to contain a @samp{=}, while the
@sc{posix} spec does not; the portion of @var{name} up to but not including
the @samp{=} will be used as the name for the environment variable.
@end enumerate
@c -----------------------------------------------------------------------------
@node setftime, setgid, setenv, Alphabetical List
@unnumberedsec setftime
@c From file ./dos/dos/setftime.txh
@findex setftime
@subheading Syntax

@example
#include <dos.h>

int setftime(int handle, struct ftime *ftimep);
@end example

@subheading Description

This function sets the modification time of a file.  Note that since
writing to a file and closing a file opened for writing also sets the
modification time, you should only use this function on files opened for
reading.

@xref{getftime}, for the description of @code{struct ftime}.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
int q = open("data.txt", O_RDONLY);
struct ftime f;
f.ft_tsec = f.ft_min = f.ft_hour = f.ft_day = f.ft_month = f.ft_year = 0;
setftime(q, &f);
close(q);
@end example

@c -----------------------------------------------------------------------------
@node setgid, setgrent, setftime, Alphabetical List
@unnumberedsec setgid
@c From file ./posix/unistd/setgid.txh
@findex setgid
@subheading Syntax

@example
#include <unistd.h>

int setgid(gid_t gid);
@end example

@subheading Description

This function is simulated, since MS-DOS does not support group IDs.

@subheading Return Value

If @var{gid} is equal to that returned by @pxref{getgid}, returns zero.
Otherwise, returns -1 and sets @code{errno} to EPERM.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node setgrent, setitimer, setgid, Alphabetical List
@unnumberedsec setgrent
@c From file ./posix/grp/getgrent.txh
@findex setgrent
@subheading Syntax

@example
#include <grp.h>

void setgrent(void);
@end example

@subheading Description

This function should be called before any call to @code{getgrent},
@code{getgrgid}, or @code{getgrnam}, to start searching the groups' list
from the beginning.  @xref{getgrent}.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node setitimer, setjmp, setgrent, Alphabetical List
@unnumberedsec setitimer
@c From file ./posix/signal/itimer.txh
@findex setitimer
@tindex itimerval@r{ structure}
@subheading Syntax

@example
#include <sys/time.h>

extern long __djgpp_clock_tick_interval;

struct timeval @{
  time_t tv_sec;
  long tv_usec;
@};

struct itimerval @{
  struct timeval it_interval;    /* timer interval */
  struct timeval it_value;       /* current value */
@};

int setitimer(int which, struct itimerval *value,
              struct itimerval *ovalue);
@end example

@subheading Description

Each process has two interval timers, @code{ITIMER_REAL} and
@code{ITIMER_PROF}, which raise the signals @code{SIGALRM} and
@code{SIGPROF}, respectively.  These are typically used to provide
@code{alarm} and profiling capabilities.

This function changes the current value of the interval timer specified by
@var{which} to the values in structure @var{value}.  The previous value
of the timer is returned in @var{ovalue} if it is not a @code{NULL}
pointer.  When the timer expires, the appropriate signal is raised.

Please see the documentation for @code{signal} (@pxref{signal})
for restrictions on signal handlers.

If @var{value} is a @code{NULL} pointer, @code{setitimer} stores the
previous timer value in @var{ovalue} (if it is non-@code{NULL}), like
@code{getitimer} does, but otherwise does nothing.

A timer is defined by the @code{itimerval} structure.  If the
@code{it_value} member is non-zero it specifies the time to the next
timer expiration.  If @code{it_interval} is non-zero, it specifies the
value with which to reload the timer upon expiration.  Setting
@code{it_value} to zero disables a timer.  Setting @code{it_interval} to
zero causes the timer to stop after the next expiration (assuming that
@code{it_value} is non-zero).

Although times can be given with microsecond resolution, the granularity
is determined by the timer interrupt frequency.  Time values smaller
than the system clock granularity will be rounded up to that
granularity, before they are used.  This means that passing a very small
but non-zero value in @samp{value->it_interval.tv_usec} will cause the
system clock granularity to be stored and returned by the next call to
@code{getitimer}.  See the example below.

If an application changes the system clock speed by reprogramming the
timer chip, it should make the new clock speed known to
@code{setitimer}, otherwise intervals smaller than the default PC clock
speed cannot be set with a call to @code{setitimer} due to rounding up
to clock granularity.  To this end, an external variable
@code{__djgpp_clock_tick_interval} is provided, which should be set to
the number of microseconds between two timer ticks that trigger
Interrupt 8.  The default value of this variable is @code{-1}, which
causes @code{setitimer} to work with 54926 microsecond granularity that
corresponds to the standard 18.2@dmn{Hz} clock frequency.  The library
never changes the value of @code{__djgpp_clock_tick_interval}.

@subheading Return Value

Returns 0 on success, -1 on failure (and sets @code{errno}).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Bugs

This version uses @code{uclock} (@pxref{uclock}) to determine the time
of expiration.  Under Windows 3.X, this fails because the OS reprograms
the timer.  Under Windows 9X, @code{uclock} sometimes reports
erratic (non-increasing) time values; in these cases the timer might
fire at a wrong time.

A misfeature of Windows 9X prevents the timer tick interrupt from being
delivered to programs that are in the background (i.e. don't have the
focus), even though the program itself might continue to run, if you
uncheck the @cite{Background: Always suspend} property in the Property
Sheets.  Therefore, the timers will not work in background programs on
Windows 9X.

Also, debuggers compiled with DJGPP v2.02 and earlier cannot cope with
timers and report @code{SIGSEGV} or @code{SIGABRT}, since signals were
not supported in a debugged program before DJGPP v2.03.

@subheading Example

@example
/* Find out what is the system clock granularity.  */

  struct itimerval tv;

  tv.it_interval.tv_sec = 0;
  tv.it_interval.tv_usec = 1;
  tv.it_value.tv_sec = 0;
  tv.it_value.tv_usec = 0;
  setitimer (ITIMER_REAL, &tv, 0);
  setitimer (ITIMER_REAL, 0, &tv);
  printf ("System clock granularity: %ld microseconds.\n",
	  tv.it_interval.tv_usec);
@end example
@c -----------------------------------------------------------------------------
@node setjmp, setlinebuf, setitimer, Alphabetical List
@unnumberedsec setjmp
@c From file ./ansi/setjmp/setjmp.txh
@findex setjmp
@subheading Syntax

@example
#include <setjmp.h>

int setjmp(jmp_buf j);
@end example

@subheading Description

This function stores the complete CPU state into @var{j}.  This
information is complete enough that @code{longjmp} (@pxref{longjmp}) can
return the program to that state.  It is also complete enough to
implement coroutines.

@subheading Return Value

This function will return zero if it is returning from its own call. 
If longjmp is used to restore the state, it will return whatever value
was passed to longjmp, except if zero is passed to longjmp it will
return one. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
jmp_buf j;
if (setjmp(j))
  return;
do_something();
longjmp(j, 1);
@end example

@c -----------------------------------------------------------------------------
@node setlinebuf, setlocale, setjmp, Alphabetical List
@unnumberedsec setlinebuf
@c From file ./ansi/stdio/setlineb.txh
@findex setlinebuf
@subheading Syntax

@example
#include <stdio.h>

void setlinebuf(FILE *file);
@end example

@subheading Description

This function modifies the buffering characteristics of @var{file}. 
First, if the file already has a buffer, it is freed.  If there was any
pending data in it, it is lost, so this function should only be used
immediately after a call to @code{fopen}.

Next, a buffer is allocated and the file is set to line buffering.

@xref{setbuf}.
@xref{setlinebuf}.
@xref{setvbuf}.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
setlinebuf(stderr);
@end example

@c -----------------------------------------------------------------------------
@node setlocale, setmntent, setlinebuf, Alphabetical List
@unnumberedsec setlocale
@c From file ./ansi/locale/setlocal.txh
@findex setlocale
@subheading Syntax

@example
#include <locale.h>

char *setlocale(int category, const char *locale);
@end example

@subheading Description

This function sets part or all of the current locale.  The
@var{category} is one of the following:

@table @code

@item LC_ALL

Set all parts of the locale.

@item LC_COLLATE

Set the collating information.

@item LC_CTYPE

Set the character type information.

@item LC_MONETARY

Set the monetary formatting information.

@item LC_NUMERIC

Set the numeric formatting information.

@item LC_TIME

Set the time formatting information.

@end table

The @var{locale} should be the name of the current locale.  Supported
locales includes user default locale (in this case settings obtained from
the @var{country.sys} driver) and standard "C" and "POSIX" locales. You
may address to user default locale by it's name if you want. If the
@var{locale} is NULL, no action is performed.  If @var{locale} is "", the
locale is identified by environment variables.  

Due to limitations of the @file{country.sys} driver only
the current user locale @code{""} or its name in the POSIX-like form
@code{"@var{LL}_@var{TT}@var{ECU}.@var{CP}"}, and @code{"C"} (aka
@code{"POSIX"}) locales are supported.  

@cindex locale code format
The POSIX-like locale code
@code{"@var{LL}_@var{TT}@var{ECU}.@var{CS}"} consists of the ISO two
letter lowercase language code @var{LL}, the ISO two letter uppercase
territory code @var{TT}, optionally followed by the suffix
@code{"_EURO"} for @var{ECU} if the country has adopted the Euro as
its currency unit, and the character set @var{CS} specified by a code
page number between 1 and 65534;
for example, @samp{"de_AT.850"} for the German-speaking Austrian
locale, or @samp{"fr_BE_EURO.850"} for the French-speaking Belgian
locale using the Euro, both using Western multilingual ``Latin-1''
code page number 850.  

@xref{localeconv}.

@subheading Return Value

A static string naming the current locale for the given category, or
NULL if the requested locale is not supported.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
setlocale(LC_ALL, "C");
@end example


@c -----------------------------------------------------------------------------
@node setmntent, setmode, setlocale, Alphabetical List
@unnumberedsec setmntent
@c From file ./compat/mntent/mntent.txh
@findex setmntent
@subheading Syntax

@example
#include <mntent.h>

FILE *setmntent(char *filename, const char *mode);
@end example

@subheading Description

This function returns an open @code{FILE*} pointer which can be used by
@code{getmntent} (@pxref{getmntent}).  The arguments @var{filename} and
@var{mode} are always ignored under MS-DOS, but for portability should
be set, accordingly, to the name of the file which describes the mounted
filesystems and the open mode of that file (like the @var{mode} argument
to @code{fopen}, @pxref{fopen}).  (There is no single standard for the
name of the file that keeps the mounted filesystems, but it is usually,
although not always, listed in the header @code{<mntent.h>}.)

@subheading Return Value

The @code{FILE*} pointer is returned.  For MS-DOS, this @code{FILE*} is
not a real pointer and may only be used by @code{getmntent}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
#include <mntent.h>
#if defined(MNT_MNTTAB)
#define MNTTAB_FILE MNT_MNTTAB
#elif defined(MNTTABNAME)
#define MNTTAB_FILE MNTTABNAME
#else
#define MNTTAB_FILE "/etc/mnttab"
#endif

  FILE *mnt_fp = setmntent (MNTTAB_FILE, "r");
@end example

@c -----------------------------------------------------------------------------
@node setmode, setpgid, setmntent, Alphabetical List
@unnumberedsec setmode
@c From file ./dos/io/setmode.txh
@findex setmode
@subheading Syntax

@example
#include <io.h>

int setmode(int file, int mode);
@end example

@subheading Description


This function sets the mode of the given @var{file} to @var{mode}, which
is either @code{O_TEXT} or @code{O_BINARY}.  It will also set the file
into either cooked or raw mode accordingly, and set any @code{FILE*}
objects that use this file into text or binary mode. 

When called to put @var{file} that refers to the console into binary
mode, @code{setmode} will disable the generation of the signals
@code{SIGINT} and @code{SIGQUIT} when you press, respectively,
@kbd{Ctrl-@key{C}} and @kbd{Ctrl-@key{\}} (@kbd{Ctrl-@key{BREAK}} will
still cause @code{SIGINT}), because many programs that use binary reads
from the console will also want to get the @samp{^C} and @samp{^\} keys.
You can use the  @code{__djgpp_set_ctrl_c} library function
(@pxref{__djgpp_set_ctrl_c}) if you want @kbd{Ctrl-@key{C}} and
@kbd{Ctrl-@key{\}} to generate signals while console is read in
binary mode.

Note that, for buffered streams (@code{FILE*}), you must call
@code{fflush} (@pxref{fflush}) before @code{setmode}, or call
@code{setmode} before writing anything to the file, for proper
operation.

@subheading Return Value

When successful, the function will return the previous mode of the
given @var{file}.  In case of failure, -1 is returned and @code{errno}
is set.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
setmode(0, O_BINARY);
@end example

@c -----------------------------------------------------------------------------
@node setpgid, setpwent, setmode, Alphabetical List
@unnumberedsec setpgid
@c From file ./posix/unistd/setpgid.txh
@findex setpgid
@subheading Syntax

@example
#include <unistd.h>

int setpgid(pid_t _pid, pid_t _pgid);
@end example

@subheading Return Value

-1 (EPERM) if _pgid is not your current pid, else zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node setpwent, setrlimit, setpgid, Alphabetical List
@unnumberedsec setpwent
@c From file ./posix/pwd/pwent.txh
@findex setpwent
@subheading Syntax

@example
#include <pwd.h>

void setpwent(void);
@end example

@subheading Description

This function reinitializes @code{getpwent} so that scanning will start
from the start of the list.  @xref{getpwent}.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node setrlimit, setsid, setpwent, Alphabetical List
@unnumberedsec setrlimit
@c From file ./compat/sys/resource/strlimit.txh
@findex setrlimit
@subheading Syntax

@example
#include <sys/resource.h>

int setrlimit (int rltype, const struct rlimit *rlimitp);
@end example

@subheading Description

This function sets new limit pointed to by @var{rlimitp} on the
resource limit specified by @var{rltype}.  Note that currently it
always fails.

@subheading Return Value

Zero on success, nonzero on failure.



@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node setsid, setstate, setrlimit, Alphabetical List
@unnumberedsec setsid
@c From file ./posix/unistd/setsid.txh
@findex setsid
@subheading Syntax

@example
#include <unistd.h>

pid_t setsid(void);
@end example

@subheading Description

This function does not do anything. It exists to assist porting from Unix.

@subheading Return Value

Return value of @pxref{getpid}.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node setstate, settime, setsid, Alphabetical List
@unnumberedsec setstate
@c From file ./compat/stdlib/random.txh
@findex setstate
@subheading Syntax

@example
#include <stdlib.h>

char *setstate(char *arg_state);
@end example

@subheading Description

Restores the random number generator (@pxref{random}) state from pointer
@var{arg_state} to state array.

@subheading Return Value

Pointer to old state information.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node settime, settimeofday, setstate, Alphabetical List
@unnumberedsec settime
@c From file ./dos/dos/settime.txh
@findex settime
@subheading Syntax

@example
#include <dos.h>

void settime(struct time *ptr);
@end example

@subheading Description

This function sets the current time.

For the description of @code{struct time}, see @ref{gettime}.  Also see
@ref{setdate}.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
struct time t;
settime(&t);
@end example

@c -----------------------------------------------------------------------------
@node settimeofday, setuid, settime, Alphabetical List
@unnumberedsec settimeofday
@c From file ./compat/time/settimeo.txh
@findex settimeofday
@subheading Syntax

@example
#include <time.h>

int settimeofday(struct timeval *tp, ...);
@end example

@subheading Description

Sets the current GMT time.  For compatibility, a second argument is
accepted.  @xref{gettimeofday}, for information on the structure types.

@subheading Return Value

Zero if the time was set, nonzero on error.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node setuid, setvbuf, settimeofday, Alphabetical List
@unnumberedsec setuid
@c From file ./posix/unistd/setuid.txh
@findex setuid
@subheading Syntax

@example
#include <unistd.h>

int setuid(uid_t uid);
@end example

@subheading Description

This function is simulated, since MS-DOS does not support user IDs.

@subheading Return Value

If @var{uid} is equal to that returned by @pxref{getuid}, returns zero.
Otherwise, returns -1 and sets @code{errno} to EPERM.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node setvbuf, sigaction, setuid, Alphabetical List
@unnumberedsec setvbuf
@c From file ./ansi/stdio/setvbuf.txh
@findex setvbuf
@subheading Syntax

@example
#include <stdio.h>

int setvbuf(FILE *file, char *buffer, int type, int length);
@end example

@subheading Description

This function modifies the buffering characteristics of @var{file}. 
First, if the file already has a buffer, it is freed.  If there was any
pending data in it, it is lost, so this function should only be used
immediately after a call to @code{fopen}.

If the @var{type} is @code{_IONBF}, the @var{buffer} and @var{length}
are ignored and the file is set to unbuffered mode. 

If the @var{type} is @code{_IOLBF} or @code{_IOFBF}, then the file is
set to line or fully buffered, respectively.  If @var{buffer} is
@code{NULL}, a buffer of size @var{size} is created and used as the
buffer.  If @var{buffer} is non-@code{NULL}, it must point to a buffer
of at least size @var{size} and will be used as the buffer. 

@xref{setbuf}.
@xref{setbuffer}.
@xref{setlinebuf}.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
setvbuf(stderr, NULL, _IOLBF, 1000);
@end example

@c -----------------------------------------------------------------------------
@node sigaction, sigaddset, setvbuf, Alphabetical List
@unnumberedsec sigaction
@c From file ./posix/signal/sigactio.txh
@findex sigaction
@tindex sigaction@r{ structure}
@subheading Syntax

@example
#include <signal.h>

int sigaction (int sig, const struct sigaction *act,
               struct sigaction *oact);
@end example

@subheading Description

This function allows to examine and/or change the action associated with
a signal @var{sig}.  The @code{struct sigaction} structure, defined by
the header file @file{signal.h}, is declared as follows:

@example
 struct sigaction @{
   int sa_flags;             /* flags for the action;
                              * currently ignored */
   void (*sa_handler)(int);  /* the handler for the signal */
   sigset_t sa_mask;         /* additional signals to be blocked */
 @};
@end example

The @code{sa_handler} member is a signal handler, see @ref{signal}.  The
@code{sa_mask} member defines the signals, in addition to @var{sig},
which are to be blocked during the execution of @code{sa_handler}.

The @code{sigaction} function sets the structure pointed to by
@code{oact} to the current action for the signal @var{sig}, and then
sets the new action for @var{sig} as specified by @var{act}.  If the
@var{act} argument is @code{NULL}, @code{sigaction} returns the current
signal action in @var{oact}, but doesn't change it.  If the @var{oact}
argument is a @code{NULL} pointer, it is ignored.  Thus, passing
@code{NULL} pointers for both @code{act} and @code{oact} is a way to
see if @var{sig} is a valid signal number on this system (if not,
@code{sigaction} will return -1 and set @code{errno}).

@subheading Return Value

0 on success, -1 for illegal value of @var{sig}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node sigaddset, sigdelset, sigaction, Alphabetical List
@unnumberedsec sigaddset
@c From file ./posix/signal/sigaddse.txh
@findex sigaddset
@subheading Syntax

@example
#include <signal.h>

int sigaddset (sigset_t *set, int signo)
@end example

@subheading Description

This function adds the individual signal specified by @var{signo} the
set of signals pointed to by @var{set}.

@subheading Return Value

0 upon success, -1 if @var{set} is a NULL pointer, or if @var{signo} is
specifies an unknown signal.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node sigdelset, sigemptyset, sigaddset, Alphabetical List
@unnumberedsec sigdelset
@c From file ./posix/signal/sigdelse.txh
@findex sigdelset
@subheading Syntax

@example
#include <signal.h>

int sigdelset (sigset_t *set, int signo)
@end example

@subheading Description

This function removes the individual signal specified by @var{signo}
from the set of signals pointed to by @var{set}.

@subheading Return Value

0 upon success, -1 if @var{set} is a NULL pointer, or if @var{signo} is
specifies an unknown signal.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node sigemptyset, sigfillset, sigdelset, Alphabetical List
@unnumberedsec sigemptyset
@c From file ./posix/signal/sigempty.txh
@findex sigemptyset
@subheading Syntax

@example
#include <signal.h>

int sigemptyset (sigset_t *set)
@end example

@subheading Description

This function initializes the set of signals pointed to by @var{set} to
exclude all signals known to the DJGPP runtime system.  Such an empty
set, if passed to @code{sigprocmask} (@pxref{sigprocmask}), will cause
all signals to be passed immediately to their handlers.

@subheading Return Value

0 upon success, -1 if @var{set} is a NULL pointer.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node sigfillset, sigismember, sigemptyset, Alphabetical List
@unnumberedsec sigfillset
@c From file ./posix/signal/sigfills.txh
@findex sigfillset
@subheading Syntax

@example
#include <signal.h>

int sigfillset (sigset_t *set)
@end example

@subheading Description

This function initializes the set of signals pointed to by @var{set} to
include all signals known to the DJGPP runtime system.  Such a full
set, if set by @code{sigprocmask} (@pxref{sigprocmask}), will cause
all signals to be blocked from delivery to their handlers.  Note that
the set returned by this function only includes signals in the range
@code{SIGABRT..SIGTRAP}; software interrupts and/or user-defined signals
aren't included.

@subheading Return Value

0 upon success, -1 if @var{set} is a NULL pointer.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example

  sigset_t full_set, prev_set;

  sigfillset (&full_set);
  sigprocmask (SIG_UNBLOCK, &full_set, &prev_set);

@end example
@c -----------------------------------------------------------------------------
@node sigismember, siglongjmp, sigfillset, Alphabetical List
@unnumberedsec sigismember
@c From file ./posix/signal/sigismem.txh
@findex sigismember
@subheading Syntax

@example
#include <signal.h>

int sigismember (sigset_t *set, int signo)
@end example

@subheading Description

This function checks whether the signal specified by @var{signo} is a
member of the set of signals pointed to by @var{set}.

@subheading Return Value

1 if the specified signal is a member of the set, 0 if it isn't, or if
@var{signo} specifies an unknown signal, -1 if @var{set} is a NULL
pointer.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node siglongjmp, signal, sigismember, Alphabetical List
@unnumberedsec siglongjmp
@c From file ./posix/setjmp/siglongj.txh
@findex siglongjmp
@subheading Syntax

@example
#include <setjmp.h>

void	siglongjmp(sigjmp_buf env, int val);
@end example

@subheading Description

@xref{longjmp}.

@subheading Return Value

This function does not return.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node signal, signbit, siglongjmp, Alphabetical List
@unnumberedsec signal
@c From file ./go32/dpmiexcp.txh
@findex signal
@subheading Syntax

@example
#include <signal.h>

void	(*signal(int sig, void (*func)(int)))(int);
@end example

@subheading Description

Signals are generated in response to some exceptional behavior of the
program, such as division by 0.  A signal can also report some
asynchronous event outside the program, such as someone pressing a
@kbd{Ctrl-@key{BREAK}} key combination.

Signals are numbered 0..255 for software interrupts and 256..287 for
exceptions (exception number plus 256); other implementation-specific
codes are specified in @code{<signal.h>} (see below).  Every signal is
given a mnemonic which you should use for portable programs.

By default, signal @code{SIGQUIT} is discarded.  This is so programs
ported from other DOS environments, where @code{SIGQUIT} is generally
not supported, continue to work as they originally did.  If you want
@code{SIGQUIT} to abort with a traceback, install
@code{__djgpp_traceback_exit} as its handler
(@pxref{__djgpp_traceback_exit}).

The default handling for the rest of the signals is to print a traceback (a
stack dump which describes the sequence of function calls leading to the
generation of the signal) and abort the program by calling @code{_exit}
(@pxref{_exit}).  As an exception, the default handler for the signal
@code{SIGINT} doesn't print the traceback, and calls @code{exit} instead
of @code{_exit}, when the INTR key (@kbd{Ctrl-C} by default) is pressed,
so that programs could be shut down safely in this manner.
@code{SIGINT} raised by @kbd{Ctrl-@key{BREAK}} does generate the
traceback.

The function @code{signal} allows you to change the default behavior for
a specific signal.  It registers @var{func} as a signal handler for
signal number @var{sig}.  After you register your function as the
handler for a particular signal, it will be called when that signal
occurs.  The execution of the program will be suspended until the
handler returns or calls @code{longjmp} (@pxref{longjmp}).

The state of the floating-point unit (FPU) is not saved, before
entering a signal handler.  It can be extremely costly to save
the FPU state.  Most signal handlers do not use floating-point
operations, so the overhead of saving FPU state is avoided.
An example of a signal handler that saves the FPU state is
the function @code{dbgsig} in @file{src/debug/common/dbgcom.c}
in the DJGPP sources.

You may pass @code{SIG_DFL} as the value of @var{func} to reset the
signal handling for the signal @var{sig} to default (also
@xref{__djgpp_exception_toggle}, for a quick way to restore all the
signals' handling to default), @code{SIG_ERR} to force an error when
that signal happens, or @code{SIG_IGN} to ignore that signal.  Signal
handlers that you write are regular C functions, and may call any
function that the ANSI/POSIX specs say are valid for signal handlers.
For maximum portability, a handler for hardware interrupts and processor
exceptions should only make calls to @code{signal}, assign values to
data objects of type @code{volatile sig_atomic_t} (defined as @code{int}
on @code{<signal.h>}) and return.  Handlers for hardware interrupts need
also be locked in memory (so that the operation of virtual memory
mechanism won't swap them out), @xref{__dpmi_lock_linear_region, locking
memory regions}.  Handlers for software interrupts can also terminate by
calling @code{abort}, @code{exit} or @code{longjmp}.

The following signals are defined on @code{<signal.h>}:

@table @code

@item SIGABRT

The Abort signal.  Currently only used by the @code{assert} macro to
terminate the program when an assertion fails (@pxref{assert}), and by
the @code{abort} function (@pxref{abort}).

@item SIGFPE

The Floating Point Error signal.  Generated in case of divide by zero
exception (Int 00h), overflow exception (Int 04h), and any x87
co-processor exception, either generated by the CPU (Int 10h), or by the
co-processor itself (Int 75h).  The co-processor status word is printed
by the default handler for this signal.  @xref{_status87}, for the
definition of the individual bits of the status word.

The DJGPP startup code masks all numeric exceptions, so this signal is
usually only triggered by an integer divide by zero operation.  If you
want to unmask some of the numeric exceptions, see @ref{_control87}.

@item SIGILL

The Invalid Execution signal.  Currently only generated for
unknown/invalid exceptions.

@item SIGINT

The Interrupt signal.  Generated when an INTR key (@kbd{Ctrl-C} by
default) or @kbd{Ctrl-@key{BREAK}} (Int 1Bh) key is hit.
Note that when you open the console in binary
mode, or switch it to binary mode by a call to @code{setmode}
(@pxref{setmode}), generation of @code{SIGINT} as result of @kbd{Ctrl-C}
key is disabled.  This is so for programs (such as Emacs) which want to
be able to read the @samp{^C} character as any other character.  Use the
library function @code{__djgpp_set_ctrl_c} to restore @code{SIGINT}
generation when @kbd{Ctrl-C} is hit, if you need this.
@xref{__djgpp_set_ctrl_c}, for details on how this should be done.
@kbd{Ctrl-@key{BREAK}} always generates @code{SIGINT}.

DJGPP hooks the keyboard hardware interrupt (Int 09h) to be able to
generate @code{SIGINT} in response to the INTR key; you should be
aware of this when you install a handler for the keyboard interrupt.

Note that the key which generates @code{SIGINT} can be changed with a
call to @code{__djgpp_set_sigint_key} function.
@xref{__djgpp_set_sigint_key}.

@item SIGSEGV

The invalid storage access (Segmentation Violation) signal.  Generated
in response to any of the following exceptions: Bound range exceeded in
BOUND instruction (Int 05h), Double Exception or an exception in the
exception handler (Int 08h), Segment Boundary violation by co-processor
(Int 09h), Invalid TSS (Int 0Ah), Segment Not Present (Int 0Bh), Stack
Fault (Int 0Ch), General Protection Violation (Int 0Dh), or Page Fault
(Int 0Eh).  Note that Int 09h is only generated on 80386 processor; i486
and later CPUs cause Int 0Dh when the co-processor accesses memory out
of bounds.  The Double Exception, Invalid TSS, Segment Not Present,
Stack Fault, GPF, and Page Fault exceptions will cause an error code to
be printed, if it is non-zero.

@item SIGTERM

The Termination Request signal.  Currently unused.


The signals below this are not defined by ANSI C, and cannot be used
when compiling under @samp{-ansi} option to @samp{gcc}.


@item SIGALRM

The Alarm signal.  Generated after certain time period has passed after
a call to @code{alarm} library function (@pxref{alarm}).

@item SIGHUP

The Hang-up signal.  Currently unused.

@item SIGKILL

The Kill signal.  Currently unused.

@item SIGPIPE

The Broken Pipe signal.  Currently unused.

@item SIGQUIT

The Quit signal.  Generated when the QUIT key (@kbd{Ctrl-\} by default)
is hit.  The key that raises the signal can be changed with a call to
@code{__djgpp_set_sigquit_key} function.
@xref{__djgpp_set_sigquit_key}.  By default, @code{SIGQUIT} is
discarded, even if its handler is @code{SIG_DFL}, so that DOS programs
which don't expect it do not break.  You can change the effect of
@code{SIGQUIT} to abort with traceback by installing
@code{__djgpp_traceback_exit} as its handler.
@xref{__djgpp_traceback_exit}.

DJGPP hooks the keyboard hardware interrupt (Int 09h) to be able to
generate @code{SIGQUIT} in response to the QUIT key; you should be
aware of this when you install a handler for the keyboard interrupt.

@item SIGUSR1

User-defined signal no. 1.

@item SIGUSR2

User-defined signal no. 2.


The signals below are not defined by ANSI C and POSIX, and cannot be
used when compiling under either @samp{-ansi} or @samp{-posix} options
to @samp{gcc}.


@item SIGTRAP

The Trap Instruction signal.  Generated in response to the Debugger
Exception (Int 01h) or Breakpoint Exception (Int 03h).

@item SIGNOFP

The No Co-processor signal.  Generated if a co-processor (floating-point)
instruction is encountered when no co-processor is installed (Int 07h).

@item SIGTIMR

The Timer signal.  Used by the @code{setitimer} and @code{alarm} functions
(@xref{setitimer}, and @pxref{alarm}).

@item SIGPROF

The Profiler signal.  Used by the execution profile gathering code in a
program compiled with @samp{-pg} option to @samp{gcc}.

@end table


@subheading Return Value

The previous handler for signal @var{sig}, or @code{SIG_ERR} if the
value of @var{sig} is outside legal limits.

@subheading Signal Mechanism Implementation Notes

Due to subtle aspects of protected-mode programs operation under MS-DOS,
signal handlers cannot be safely called from hardware interrupt
handlers.  Therefore, DJGPP exception-handling mechanism arranges for
the signal handler to be called on the first occasion that the program
is in protected mode and touches any of its data.  This means that if
the exception occurs while the processor is in real mode, like when your
program calls some DOS service, the signal handler won't be called until
that call returns.  For instance, if you call @code{read} (or
@code{scanf}, or @code{gets}) to read text from the console and press
@kbd{Ctrl-C}, you will have to press @kbd{Enter} to terminate the
@code{read} call to cause the signal handler for @code{SIGINT} to be
called.  Another significant implication of this implementation is that
when the program isn't touching any of its data (like in very tight
loops which only use values in the registers), it cannot be interrupted.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable



@c -----------------------------------------------------------------------------
@node signbit, __signbitd, signal, Alphabetical List
@unnumberedsec signbit
@c From file ./c99/math/signbit.txh
@findex signbit
@subheading Syntax

@example
#include <math.h>

int signbit(x);
@end example

@subheading Description

The macro @code{signbit} returns 0 if the sign of the mantissa of the floating
point number @var{x} is positive else it returns non-zero.

@subheading Return Value

zero for positive floating point numbers;
non-zero for negative floating point numbers.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@end multitable


@subheading Example

@example
float f = 1;
double d = INFINITY;
long double ld = NAN;

printf("value is %s.\n", (signbit(f)) ? "negative" : "positive");
printf("value is %s.\n", (signbit(d)) ? "negative" : "positive");
printf("value is %s.\n", (signbit(ld)) ? "negative" : "positive");

@end example
@c -----------------------------------------------------------------------------
@node __signbitd, __signbitf, signbit, Alphabetical List
@unnumberedsec __signbitd
@c From file ./c99/math/sgnbitd.txh
@findex __signbitd
@subheading Syntax

@example
#include <math.h>

int __signbitd(double x);
@end example

@subheading Description

Returns 0 if the sign of the mantissa of the floating
point number @var{x} is positive else it returns non-zero.
You should use the type generic macro @code{signbit} (@pxref{signbit})
instead of this function.

@subheading Return Value

zero for positive floating point numbers;
non-zero for negative floating point numbers.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@end multitable


@subheading Example

@example

printf("double value is %s.\n", (__signbitd(0.0)) ? "negative" : "positive");

@end example
@c -----------------------------------------------------------------------------
@node __signbitf, __signbitld, __signbitd, Alphabetical List
@unnumberedsec __signbitf
@c From file ./c99/math/sgnbitf.txh
@findex __signbitf
@subheading Syntax

@example
#include <math.h>

int __signbitf(float x);
@end example

@subheading Description

Returns 0 if the sign of the mantissa of the floating
point number @var{x} is positive else it returns non-zero.
You should use the type generic macro @code{signbit} (@pxref{signbit})
instead of this function.

@subheading Return Value

zero for positive floating point numbers;
non-zero for negative floating point numbers.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@end multitable


@subheading Example

@example

printf("float value is %s.\n", (__signbitf(0.0F)) ? "negative" : "positive");

@end example
@c -----------------------------------------------------------------------------
@node __signbitld, sigpending, __signbitf, Alphabetical List
@unnumberedsec __signbitld
@c From file ./c99/math/sgnbitld.txh
@findex __signbitld
@subheading Syntax

@example
#include <math.h>

int __signbitld(long double x);
@end example

@subheading Description

Returns 0 if the sign of the mantissa of the floating
point number @var{x} is positive else it returns non-zero.
You should use the type generic macro @code{signbit} (@pxref{signbit})
instead of this function.

@subheading Return Value

zero for positive floating point numbers;
non-zero for negative floating point numbers.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@end multitable


@subheading Example

@example

printf("long double value is %s.\n", (__signbitld(0.0L)) ? "negative" : "positive");

@end example
@c -----------------------------------------------------------------------------
@node sigpending, sigprocmask, __signbitld, Alphabetical List
@unnumberedsec sigpending
@c From file ./posix/signal/sigprocm.txh
@findex sigpending
@subheading Syntax

@example
#include <signal.h>

int sigpending (sigset_t *set)
@end example

@subheading Description

This function retrieves the signals that have been sent to the program,
but are being blocked from delivery by the program's signal mask
(@pxref{sigprocmask}).  The bit-mapped value which describes the pending
signals is stored in the structure pointed to by @var{set}.  You can use
the @code{sigismember} function (@pxref{sigismember}) to see what
individual signals are pending.

@subheading Return Value

0 on success, -1 on failure (and errno set to @code{EFAULT}).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example

#include <signal.h>

  sigset_t pending_signals;

  /* If SIGINT is pending, force it to be raised.  */
  if (sigpending (&pending_signals) == 0
      && sigismember (&pending_signals, SIGINT))
    @{
      sigset_t new_set, old_set;
      sigemptyset (&new_set);
      sigaddset (&new_set, SIGINT);

      /* This sigprocmask() call will raise SIGINT. */
      sigprocmask (SIG_UNBLOCK, &new_set, &old_set);

      /* Restore mask */
      sigprocmask (SIG_SETMASK, &old_set, &new_set);
    @}

@end example
@c -----------------------------------------------------------------------------
@node sigprocmask, sigsetjmp, sigpending, Alphabetical List
@unnumberedsec sigprocmask
@c From file ./posix/signal/sigprocm.txh
@findex sigprocmask
@subheading Syntax

@example
#include <signal.h>

int sigprocmask (int how, const sigset_t *new_set, sigset_t *old_set)
@end example

@subheading Description

This function is used to examine and/or change the program's current
signal mask.  The current signal mask determines which signals are
blocked from being delivered to the program.  A signal is blocked if its
bit in the mask is set.  (@xref{sigismember}, @xref{sigaddset},
@xref{sigdelset}, @xref{sigemptyset}, @xref{sigfillset}, for information
about functions to manipulate the signal masks.)  When a blocked signal
happens, it is not delivered to the program until such time as that
signal is unblocked by another call to @code{sigprocmask}.  Thus
blocking a signal is an alternative to ignoring it (by setting its
handler to @code{SIG_IGN}, @pxref{signal}), but has an advantage of not
missing the signal entirely.

The value of the argument @var{how} determines the operation: if it is
@code{SIG_BLOCK}, the set pointed to by the argument @var{new_set} is
@emph{added} to the current signal mask.  If the value is
@code{SIG_UNBLOCK}, the set pointed to by @var{new_set} is
@emph{removed} from the current signal mask.  If the value is
@code{SIG_SETMASK}, the current mask is @emph{replaced} by the set
pointed to by @var{new_set}.

If the argument @var{old_set} is not @code{NULL}, the previous mask is
stored in the space pointed to by @var{old_set}.  If the value of the
argument @var{new_set} is @code{NULL}, the value of @var{how} is not
significant and the process signal mask is unchanged; thus, the call
with a zero @var{new_set} can be used to inquire about currently blocked
signals, without changing the current set.

If the new set defined by the call causes some pending signals to be
unblocked, they are all delivered (by calling @code{raise}) before the
call to @code{sigprocmask} returns.

The DJGPP implementation only records a single occurrence of any given
signal, so when the signal is unblocked, its handler will be called at
most once.

It is not possible to block CPU exceptions such as Page Fault, General
Protection Fault etc. (mapped to @code{SIGSEGV} signal); for these, 
@code{sigprocmask} will behave as if the call succeeded, but when an
exception happens, the signal handler will be called anyway (the default
handler will abort the program).

Also note that there are no provisions to save and restore any
additional info about the signal beyond the fact that it happened.  A
signal handler might need such info to handle the signal intelligently.
For example, a handler for @code{SIGFPE} might need to examine the
status word of the FPU to see what exactly went wrong.  But if the
signal was blocked and is delivered after a call to @code{sigprocmask}
has unblocked it, that information is lost.  Therefore, if you need
access to such auxiliary information in the signal handler, don't block
that signal.

@subheading Return Value

0 on success, -1 for illegal value of @var{sig} or illegal address in
@var{new_set} or @var{old_set}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example

#include <conio.h>
#include <signal.h>

static void
sig_catcher (int signo)
@{
  cprintf ("\r\nGot signal %d\r\n", signo);
@}

int
main (void)
@{
  sigset_t sigmask, prevmask;

  signal (SIGINT, sig_catcher);

  sigemptyset (&sigmask);

  sigaddset (&sigmask, SIGINT);
  if (sigprocmask (SIG_SETMASK, &sigmask, &prevmask) == 0)
    cputs ("SIGINT blocked.  Try to interrupt me now.\r\n");
  while (!kbhit ())
    ;
  cputs ("See?  I wasn't interrupted.\r\n");
  cputs ("But now I will unblock SIGINT, and then get the signal.\r\n");
  sigprocmask (SIG_UNBLOCK, &sigmask, &prevmask);
  return 0;
@}

@end example
@c -----------------------------------------------------------------------------
@node sigsetjmp, sin, sigprocmask, Alphabetical List
@unnumberedsec sigsetjmp
@c From file ./posix/setjmp/sigsetjm.txh
@findex sigsetjmp
@subheading Syntax

@example
#include <setjmp.h>

int	sigsetjmp(sigjmp_buf env, int savemask);
@end example

@subheading Description

@xref{setjmp}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node sin, sincos, sigsetjmp, Alphabetical List
@unnumberedsec sin
@c From file ./ansi/math/sin.txh
@findex sin
@subheading Syntax

@example
#include <math.h>

double sin(double x);
@end example

@subheading Description

This function computes the sine of @var{x} (which should be given in
radians).

@subheading Return Value

The sine of @var{x}.  If the absolute value of @var{x} is finite but
greater than or equal to @math{2^63}, the value is 0 (since for
arguments that large each bit of the mantissa is more than @code{Pi}).
If the value of @var{x} is infinite or @code{NaN}, the return value is
@code{NaN} and @code{errno} is set to @code{EDOM}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Accuracy

In general, this function's relative accuracy is about
@math{1.7*10^(-16)}, which is close to the machine precision for a
@code{double}.  However, for arguments very close to @code{Pi} and its
odd multiples, the relative accuracy can be many times worse, due to
loss of precision in the internal FPU computations.  Since
@math{sin(Pi)} is zero, the absolute accuracy is still very good; but if
your program needs to preserve high @emph{relative} accuracy for such
arguments, link with @samp{-lm} and use the version of @code{sin} from
@file{libm.a} which does elaborate argument reduction, but is about
three times slower.
@c -----------------------------------------------------------------------------
@node sincos, sinh, sin, Alphabetical List
@unnumberedsec sincos
@c From file ./compat/math/sincos.txh
@findex sincos
@subheading Syntax

@example
#include <math.h>

void   sincos(double x, double *sine, double *cosine);
@end example

@subheading Description

This function computes the cosine and the sine of @var{x} in a single
call, and stores the results in the addresses pointed to by @var{cosine}
and @var{sine}, respectively.  Since the function exploits a machine
instruction that computes both cosine and sine simultaneously, it is
faster to call @code{sincos} than to call @code{cos} and @code{sin} for
the same argument.

If the absolute value of @var{x} is finite but greater than or equal to
@math{2^63}, the value stored in @var{*cosine} is 1 and the value stored
in @var{*sine} is 0 (since for arguments that large each bit of the
mantissa is more than @code{Pi}).  If the value of @var{x} is infinite
or @code{NaN}, @code{NaN} is stored in both @var{*cosine} and
@var{*sine}, and @code{errno} is set to @code{EDOM}.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node sinh, sleep, sincos, Alphabetical List
@unnumberedsec sinh
@c From file ./ansi/math/sinh.txh
@findex sinh
@subheading Syntax

@example
#include <math.h>

double sinh(double x);
@end example

@subheading Description

This function computes the hyperbolic sine of @var{x}.

@subheading Return Value

The hyperbolic sine of @var{x}.  If the absolute value of @var{x} is
finite but so large that the result would overflow a @code{double}, the
return value is @code{Inf} with the same sign as @var{x}, and
@code{errno} is set to @code{ERANGE}.  If @var{x} is either a positive
or a negative infinity, the result is @code{+Inf} with the same sign as
@var{x}, and @code{errno} is not changed.  If @var{x} is @code{NaN}, the
return value is @code{NaN} and @code{errno} is set to @code{EDOM}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node sleep, snprintf, sinh, Alphabetical List
@unnumberedsec sleep
@c From file ./posix/unistd/sleep.txh
@findex sleep
@subheading Syntax

@example
#include <unistd.h>

unsigned sleep(unsigned seconds);
@end example

@subheading Description

This function causes the program to pause for @var{seconds} seconds. 

@subheading Return Value

The number of seconds that haven't passed (i.e. always zero)

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
sleep(5);
@end example

@c -----------------------------------------------------------------------------
@node snprintf, __solve_dir_symlinks, sleep, Alphabetical List
@unnumberedsec snprintf
@c From file ./ansi/stdio/snprintf.txh
@findex snprintf
@subheading Syntax

@example
#include <stdio.h>

int snprintf (char *buffer, size_t n, const char *format, @dots{});
@end example

@subheading Description

This function works similarly to @code{sprintf()} (@pxref{sprintf}), but
the size @var{n} of the @var{buffer} is also taken into account.  This
function will write @var{n} - 1 characters.  The @var{n}th character is used
for the terminating nul.  If @var{n} is zero, @var{buffer} is not touched.

@subheading Return Value

The number of characters that would have been written (excluding the trailing
nul) is returned; otherwise -1 is returned to flag encoding or buffer space
errors.

The maximum accepted value of @var{n} is @code{INT_MAX}.  @code{INT_MAX} is
defined in @code{<limits.h>}.  -1 is returned and @code{errno} is set to
@code{EFBIG}, if @var{n} is greater than this limit.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99; (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
The buffer size limit is imposed by DJGPP.  Other systems may not have this limitation.

@end enumerate
@c -----------------------------------------------------------------------------
@node __solve_dir_symlinks, __solve_symlinks, snprintf, Alphabetical List
@unnumberedsec __solve_dir_symlinks
@c From file ./compat/unistd/sdirlink.txh
@findex __solve_dir_symlinks
@subheading Syntax

@example
#include <libc/symlink.h>

int __solve_dir_symlinks(const char *symlink_path, char *real_path);
@end example

@subheading Description

This function resolves given symlink in @var{symlink_path}---all path 
components @strong{except} the last one and all symlink levels are 
resolved.  If @var{symlink_path} does not contain symlinks at all, it is 
simply copied to @var{real_path}.

@var{real_path} should be of size @code{FILENAME_MAX}, to contain
the maximum possible length of path.

@subheading Return Value

Zero in case of error (and @code{errno} set to the appropriate
error code), non-zero in case of success.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example

  #include <libc/symlink.h>
  #include <stdio.h>

  char fn[] = "c:/somelink/someotherlink/somefile";
  char file_name[FILENAME_MAX];

  __solve_dir_symlinks(fn, file_name);
  printf("The real path to %s is %s\n", fn, file_name);

@end example
@c -----------------------------------------------------------------------------
@node __solve_symlinks, sound, __solve_dir_symlinks, Alphabetical List
@unnumberedsec __solve_symlinks
@c From file ./compat/unistd/xsymlink.txh
@findex __solve_symlinks
@subheading Syntax

@example
#include <libc/symlink.h>

int __solve_symlinks(const char *symlink_path, char *real_path);
@end example

@subheading Description

This function fully resolves given symlink in @var{symlink_path}---all 
path components and all symlink levels are resolved.  The
returned path in @var{real_path} is guaranteed to be symlink-clean
and understandable by DOS.  If @var{symlink_path} does not contain
symlinks at all, it is simply copied to @var{real_path}.

@var{real_path} should be of size @code{FILENAME_MAX}, to contain
the maximum possible length of path.

@subheading Return Value

Zero in case of error (and @code{errno} set to the appropriate
error code), non-zero in case of success.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example

  #include <libc/symlink.h>
  #include <stdio.h>

  const char fn[] = "c:/somedir/somelink";
  char file_name[FILENAME_MAX];

  __solve_symlinks(fn, file_name);
  printf("File %s is really %s\n", fn, file_name);

@end example
@c -----------------------------------------------------------------------------
@node sound, spawn*, __solve_symlinks, Alphabetical List
@unnumberedsec sound
@c From file ./pc_hw/sound/sound.txh
@findex sound
@subheading Syntax

@example
#include <pc.h>

void		sound(int _frequency);
@end example

@subheading Description

Enables the PC speaker at the given frequency.  The argument
@var{_frequency} should be given in Hertz units.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node spawn*, sprintf, sound, Alphabetical List
@unnumberedsec spawn*
@c From file ./dos/process/dosexec.txh
@findex spawnl
@findex spawnle
@findex spawnlp
@findex spawnlpe
@findex spawnv
@findex spawnve
@findex spawnvp
@findex spawnvpe
@vindex COMSPEC@r{ environment variable, and }spawn*
@vindex PATH@r{ environment variable, and }spawn*
@vindex CMDLINE@r{ environment variable, and }spawn*
@subheading Syntax

@smallexample
#include <process.h>

int spawnl(int mode, const char *path, const char *argv0, ..., NULL);
int spawnle(int mode, const char *path, const char *argv0, ...,
            NULL /*, const char **envp */);
int spawnlp(int mode, const char *path, const char *argv0, ..., NULL);
int spawnlpe(int mode, const char *path, const char *argv0, ...,
             NULL /*, const char **envp */);

int spawnv(int mode, const char *path, char *const argv[]);
int spawnve(int mode, const char *path, char *const argv[],
            char *const envp[]);
int spawnvp(int mode, const char *path, char *const argv[]);
int spawnvpe(int mode, const char *path, char *const argv[],
             char *const envp[]);
@end smallexample

@subheading Description

These functions run other programs.  The @var{path} points to the
program to run, and may optionally include its extension.  These
functions will look for a file @var{path} with the extensions
@file{.com}, @file{.exe}, @file{.bat}, and @file{.btm}; if none are found,
neither in the current directory nor along the @samp{PATH}, they will look for
@var{path} itself.

@file{.com}
programs are invoked via the usual DOS calls; DJGPP @file{.exe} programs
are invoked in a way that allows long command lines to be passed; other
@file{.exe} programs are invoked via DOS; @file{.bat} and @file{.btm}
programs are invoked via the command processor given by the
@samp{COMSPEC} environment variable; @file{.sh}, @file{.ksh} programs
and programs with any other extensions that have @code{#!} as their
first two characters are assumed to be Unix-style scripts and are
invoked by calling a program whose pathname immediately follows the
first two characters.  (If the name of that program is a Unix-style
pathname, without a drive letter and without an extension, like
@samp{/bin/sh}, the @code{spawn} functions will additionally look them
up on the @samp{PATH}; this allows to run Unix scripts without editing,
if you have a shell installed somewhere along your @samp{PATH}.)  Any
non-recognizable files will be also invoked via DOS calls.

@strong{WARNING!}  DOS is rather stupid in invoking programs: if the
file doesn't have the telltale ``MZ'' signature of the @file{.exe} style
programs, DOS assumes it is a @file{.com} style image and tries to
execute it directly.  If the file is not really an executable program,
your application will almost certainly crash.  Applications that need to
be robust in such situations should test whether the program file is
indeed an executable, e.g. with calls to @code{stat} (@pxref{stat}) or
@code{_is_executable} (@pxref{_is_executable}) library functions.

Note that built-in commands of the shells can @emph{not} be invoked via
these functions; use @code{system} instead, or invoke the appropriate
shell with the built-in command as its argument.

The programs are invoked with the arguments given.  The zeroth argument
is normally not used, since MS-DOS cannot pass it separately, but for
compatibility it should be the name of the program.  There are
two ways of passing arguments.  The @code{l} functions (like
@code{spawnl}) take a list of arguments, with a @code{NULL} at the end of the
list.  This is useful when you know how many argument there will be
ahead of time.  The @code{v} functions (like @code{spawnv}) take a
pointer to a list of arguments, which also must be @code{NULL}-terminated.  
This is useful when you need to compute the number of arguments at runtime. 

In either case, you may also specify @code{e} to indicate that you will
be giving an explicit environment, else the current environment is used. 
You may also specify @code{p} to indicate that you would like
@code{spawn*} to search the @code{PATH} (in either the environment you
pass or the current environment) for the executable, else it will only
check the explicit path given. 

Note that these function understand about other DJGPP programs, and will
call them directly, so that you can pass command lines longer than 126
characters to them without any special code.  DJGPP programs called by
these functions will @emph{not} glob the arguments passed to them; other
programs also won't glob the arguments if they suppress expansion when
given quoted filenames.

When the calling program runs on Windows 9X or Windows 2000 and calls
the system shell to run the child program, or if the child program is a
native Windows program (in @code{PE-COFF} format), or when the system
shell is @file{4DOS} or @file{NDOS} and the shell is called to run the
command, command lines longer than 126 characters are passed via the
environment variable @code{CMDLINE}.

@xref{exec*}.

@subheading Return Value

If successful and @code{mode} is @code{P_WAIT}, these functions return
the exit code of the child process in the lower 8 bits of the return
value.  Note that if the program is run by a command processor (e.g., if
it's a batch file), the exit code of that command processor will be
returned.  @file{COMMAND.COM} is notorious for returning 0 even if it
couldn't run the command.

If successful and @var{mode} is @code{P_OVERLAY}, these functions will
not return. 

If there is an error (e.g., the program specified as @code{argv[0]}
cannot be run, or the command line is too long), these functions return
-1 and set @code{errno} to indicate the error.  If the child program was
interrupted by @key{Ctrl-C} or a Critical Device error, @code{errno} is
set to @code{EINTR} (even if the child's exit code is 0), and bits 8-17
of the return value are set to @code{SIGINT} or @code{SIGABRT},
accordingly.  Note that you must set the signal handler for
@code{SIGINT} to @code{SIG_IGN}, or arrange for the handler to return,
or else your program will be aborted before it will get chance to set
the value of the return code.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example

char *environ[] = @{
  "PATH=c:\\dos;c:\\djgpp;c:\\usr\\local\\bin",
  "DJGPP=c:/djgpp",
  0
@};

char *args[] = @{
  "gcc",
  "-v",
  "hello.c",
  0
@};

spawnvpe(P_WAIT, "gcc", args, environ);
@end example


@c -----------------------------------------------------------------------------
@node sprintf, sqrt, spawn*, Alphabetical List
@unnumberedsec sprintf
@c From file ./ansi/stdio/sprintf.txh
@findex sprintf
@subheading Syntax

@example
#include <stdio.h>

int sprintf(char *buffer, const char *format, @dots{});
@end example

@subheading Description

Sends formatted output from the arguments (@dots{}) to the @var{buffer}.
@xref{printf}.

To avoid buffer overruns, it is safer to use @code{snprintf()}
(@pxref{snprintf}).

@subheading Return Value

The number of characters written.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node sqrt, srand, sprintf, Alphabetical List
@unnumberedsec sqrt
@c From file ./ansi/math/sqrt.txh
@findex sqrt
@subheading Syntax

@example
#include <math.h>

double sqrt(double x);
@end example

@subheading Description

This function computes the square root of @var{x}.

@subheading Return Value

The square root of @var{x}.  If @var{x} is negative or a @code{NaN}, the
return value is @code{NaN} and @code{errno} is set to @code{EDOM}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node srand, srandom, sqrt, Alphabetical List
@unnumberedsec srand
@c From file ./ansi/stdlib/rand.txh
@findex srand
@subheading Syntax

@example
#include <stdlib.h>

void srand(unsigned seed);
@end example

@subheading Description

Initializes the random number generator for @code{rand()}.  If you
pass the same seed, @code{rand()} will return the same sequence of
numbers.  You can seed from @code{time} (@pxref{time})
or @code{rawclock} (@pxref{rawclock}).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
/* random pause */
srand(time(0));
for (i=rand(); i; i--);
@end example

@c -----------------------------------------------------------------------------
@node srandom, sscanf, srand, Alphabetical List
@unnumberedsec srandom
@c From file ./compat/stdlib/random.txh
@findex srandom
@subheading Syntax

@example
#include <stdlib.h>

int srandom(int seed);
@end example

@subheading Description

Initializes the random number generator (@pxref{random}). Passing the
same @var{seed} results in @code{random} returning predictable sequences
of numbers, unless @pxref{initstate} or @pxref{setstate} are called.

@subheading Return Value

Zero.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
srandom(45);
@end example

@c -----------------------------------------------------------------------------
@node sscanf, Stack overflow handler, srandom, Alphabetical List
@unnumberedsec sscanf
@c From file ./ansi/stdio/sscanf.txh
@findex sscanf
@subheading Syntax

@example
#include <stdio.h>

int sscanf(const char *string, const char *format, @dots{});
@end example

@subheading Description

This function scans formatted text from the @var{string} and stores it
in the variables pointed to by the arguments.  @xref{scanf}.

@subheading Return Value

The number of items successfully scanned.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node Stack overflow handler, stackavail, sscanf, Alphabetical List
@unnumberedsec Stack overflow handler
@c From file ./go32/overflow.txh
@vindex __djgpp_stack_overflow_eip
@findex __djgpp_stack_overflow_exit
@subheading Syntax

@example
extern unsigned int __djgpp_stack_overflow_eip;
void __djgpp_stack_overflow_exit(void);
@end example

@subheading Description

This is the stack overflow handler, an internal function intended to be used
only by special code generated by the compiler.  This will exit with a
suitable error message.

@subheading Return Value

This function does not return.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable

@c -----------------------------------------------------------------------------
@node stackavail, stat, Stack overflow handler, Alphabetical List
@unnumberedsec stackavail
@c From file ./compat/stdlib/stkavail.txh
@findex stackavail
@subheading Syntax

@example
#include <stdlib.h>

int stackavail(void);
@end example

@subheading Description

This function returns the number of bytes that are available on the stack.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
printf("Available stack size is %d bytes\n", stackavail());
@end example
@c -----------------------------------------------------------------------------
@node stat, statfs, stackavail, Alphabetical List
@unnumberedsec stat
@c From file ./posix/sys/stat/stat.txh
@findex stat
@tindex stat@r{ structure}
@subheading Syntax

@example
#include <sys/stat.h>

int stat(const char *file, struct stat *sbuf);
@end example

@subheading Description

This function obtains the status of the file @var{file} and stores
it in @var{sbuf}.  @code{stat} follows symbolic links.  To get
information about a symbolic link, use @code{lstat} (@pxref{lstat})
instead.

@var{sbuf} has this structure:

@smallexample
struct  stat @{
        time_t    st_atime;     /* time of last access       */
        time_t    st_ctime;     /* time of file's creation   */
        dev_t     st_dev;       /* The drive number (0 = a:) */
        gid_t     st_gid;       /* what getgid() returns */
        ino_t     st_ino;       /* starting cluster or unique identifier */
        mode_t    st_mode;      /* file mode - S_IF* and S_IRUSR/S_IWUSR */
        time_t    st_mtime;     /* time that the file was last written */
        nlink_t   st_nlink;     /* 2 + number of subdirs, or 1 for files */
        off_t     st_size;      /* size of file in bytes */
        blksize_t st_blksize;   /* block size in bytes*/
        uid_t     st_uid;       /* what getuid() returns */
	dev_t     st_rdev;      /* The drive number (0 = a:) */
@};
@end smallexample

The @code{st_atime}, @code{st_ctime} and @code{st_mtime} have different
values only when long file names are supported (e.g. on Windows 9X);
otherwise, they all have the same value: the time that the file was last
written@footnote{
Even when long file names @emph{are} supported, the three time values
returned by @code{stat} might be identical if the file was last written
by a program which used legacy DOS functions that don't know about long
file names.}.  Most Windows 9X VFAT filesystems only support the date of
the file's last access (the time is set to zero); therefore, the DJGPP
implementation of @code{stat} sets the @code{st_atime} member to the
same value as @code{st_mtime} if the time part of @code{st_atime}
returned by the filesystem is zero (to prevent the situation where the
file appears to have been created @emph{after} it was last accessed,
which doesn't look good).

The @code{st_size} member is an signed 32-bit integer type, so it will
overflow on FAT32 volumes for files that are larger than 2GB.
Therefore, if your program needs to support large files, you should
treat the value of @code{st_size} as an unsigned value.

For some drives @code{st_blksize} has a default value, to improve
performance.  The floppy drives A: and B: default to a block size
of 512 bytes.  Network drives default to a block size of 4096 bytes.

Some members of @code{struct stat} are very expensive to compute.  If
your application is a heavy user of @code{stat} and is too slow, you can
disable computation of the members your application doesn't need, as
described in @ref{_djstat_flags}.

@subheading Return Value

Zero on success, nonzero on failure (and @code{errno} set).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
struct stat s;
stat("data.txt", &s);
if (S_ISDIR(s.st_mode))
  printf("is directory\n");
@end example

@subheading Implementation Notes

Supplying a 100% Unix-compatible @code{stat} function under DOS is an
implementation nightmare.  The following notes describe some of the
obscure points specific to @code{stat}s behavior in DJGPP.

1. The @samp{drive} for character devices (like @code{con}, @code{/dev/null}
and others is returned as -1.  For drives networked by Novell Netware, it
is returned as -2.

2. The starting cluster number of a file serves as its inode number.  For
files whose starting cluster number is inaccessible (empty files, files on
Windows 9X, on networked drives, etc.) the @code{st_inode} field will be
@emph{invented}
in a way which guarantees that no two different files will get the same
inode number (thus it is unique).  This invented inode will also be
different from any real cluster number of any local file.  However, only
on plain DOS, and only for local, non-empty files/directories the inode
is guaranteed to be consistent between @code{stat}, @code{fstat} and
@code{lstat} function calls.  (Note that two files whose names are
identical but for the drive letter, will get the same invented inode,
since each filesystem has its own independent inode numbering, and
comparing files for identity should include the value of @code{st_dev}.)

3. The WRITE access mode bit is set only for the user (unless the file is
read-only, hidden or system).  EXECUTE bit is set for directories,  files
which can be executed from the DOS prompt (batch files, .com, .dll and .exe
executables) or run by @code{go32-v2}.

4. Size of directories is reported as the number of its files (sans `.' and
`..' entries) multiplied by 32 bytes (the size of directory entry).  On FAT
filesystems that support the LFN API (such as Windows 9X), the reported
size of the directory accounts for additional space used to store the long
file names.

5. Time stamp for root directories is taken from the volume label entry,
if that's available; otherwise, it is reported as 1-Jan-1980.

6. The variable @code{_djstat_flags} (@pxref{_djstat_flags}) controls
what hard-to-get fields of @code{struct stat} are needed by the
application.

7. @code{stat} should not be used to get an up-to-date info about a file
which is open and has been written to, because @code{stat} will only
return correct data after the file is closed.  Use @code{fstat}
(@pxref{fstat}) while the file is open.  Alternatively, you can call
@code{fflush} and @code{fsync} to make the OS flush all the file's data
to the disk, before calling @code{stat}.

8. The number of links @code{st_nlink} is always 1 for files other than
directories.  For directories, it is the number of subdirectories plus
2.  This is so that programs written for Unix that depend on this to
optimize recursive traversal of the directory tree, will still work.
@c -----------------------------------------------------------------------------
@node statfs, _status87, stat, Alphabetical List
@unnumberedsec statfs
@c From file ./compat/sys/vfs/statfs.txh
@findex statfs
@tindex statfs@r{ structure}
@subheading Syntax

@example
#include <sys/vfs.h>

int statfs(const char *filename, struct statfs *buf);
@end example

@subheading Description

This function returns information about the given "filesystem".  The
drive letter of the given @var{filename}, or the default drive if none
is given, is used to retrieve the following structure:

@example
struct statfs
@{
    long	f_type;   /* 0 */
    long	f_bsize;  /* bytes per cluster */
    long	f_blocks; /* clusters on drive */
    long	f_bfree;  /* available clusters */
    long	f_bavail; /* available clusters */
    long	f_files;  /* clusters on drive */
    long	f_ffree;  /* available clusters */
    fsid_t	f_fsid;   /* array: [0]=drive_number, [1]=MOUNT_UFS */
    long	f_magic;  /* FS_MAGIC */
@};
@end example

Note that if INT 21h is hooked by a TSR, the total size is limited
to approximately 2GB (@pxref{statvfs}).

Note that there is a POSIX-compliant function @code{statvfs}
(@pxref{statvfs}), which returns similar information.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
struct statfs fs;
unsigned long long bfree, bsize;

statfs("anything", &fs);
bfree = fs.f_bfree;
bsize = fs.f_bsize;
printf("%llu bytes left\n", bfree * bsize);
@end example

@c -----------------------------------------------------------------------------
@node _status87, statvfs, statfs, Alphabetical List
@unnumberedsec _status87
@c From file ./pc_hw/fpu/stat87.txh
@findex _status87
@subheading Syntax

@example
#include <float.h>

unsigned int _status87(void);
@end example

@subheading Description

Returns the status word of the FPU, which indicate the results of the
most recently completed FPU operation:

@example
---- ---- ---- ---X = SW_INVALID - invalid operation
---- ---- ---- --X- = SW_DENORMAL - denormalized operand
---- ---- ---- -X-- = SW_ZERODIVIDE - division by zero
---- ---- ---- X--- = SW_OVERFLOW - overflow
---- ---- ---X ---- = SW_UNDERFLOW - underflow
---- ---- --X- ---- = SW_INEXACT - loss of precision
---- ---- -X-- ---- = SW_STACKFAULT - stack over/under flow
---- ---- X--- ---- = SW_ERRORSUMMARY - set if any errors
-X-- -XXX ---- ---- = SW_COND - condition code
---- ---X ---- ---- = SW_C0
---- --X- ---- ---- = SW_C1
---- -X-- ---- ---- = SW_C2
-X-- ---- ---- ---- = SW_C3
--XX X--- ---- ---- = SW_TOP - top of stack (use SW_TOP_SHIFT
                                             to shift it)
X--- ---- ---- ---- = SW_BUSY - fpu is busy
@end example

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node statvfs, _stklen, _status87, Alphabetical List
@unnumberedsec statvfs
@c From file ./posix/sys/statvfs/statvfs.txh
@findex statvfs
@tindex statvfs@r{ structure}
@subheading Syntax

@example
#include <sys/types.h>
#include <sys/statvfs.h>

int statvfs (const char *path, struct statvfs *sbuf);
@end example

@subheading Description

This function returns information about the ``filesystem'' (FS)
containing @var{path} and stores it in @var{sbuf}, which has
the structure below:

@example
struct statvfs @{
  unsigned long f_bsize;   /* FS block size */
  unsigned long f_frsize;  /* fundamental block size */
  fsblkcnt_t    f_blocks;  /* # of blocks on FS of size f_frsize */
  fsblkcnt_t    f_bfree;   /* # of free blocks on FS of size f_frsize */
  fsblkcnt_t    f_bavail;  /* # of free blocks on FS of size f_frsize
                            * for unprivileged users */
  fsfilcnt_t    f_files;   /* # of file serial numbers */
  fsfilcnt_t    f_ffree;   /* # of free file serial numbers */
  fsfilcnt_t    f_favail;  /* # of free file serial numbers
                            * for unprivileged users */
  unsigned long f_fsid;    /* FS identifier */
  unsigned long f_flag;    /* FS flags: bitwise OR of ST_NOSUID,
                            * ST_RDONLY */
  unsigned long f_namemax; /* Maximum file name length on FS */
@};
@end example

Note that if INT 21h is hooked by a TSR, the total size is limited
to approximately 2GB.  TSRs that hook INT 21h include:

@itemize @bullet
@item CD-ROM drivers;
@item command-line enhancers such as CMDEDIT and Microsoft's DOSEdit.
@end itemize

These may be loaded by @file{autoexec.bat} or @file{config.sys}.

The fundamental block size is considered to be a cluster.  Really
the fundamental block is the sector of the physical media rather
than the logical block of the filesystem, but the sector size
cannot be determined in all cases.  So for consistency we return
the cluster size.

@subheading Return Value

Zero on success, nonzero on failure (and @code{errno} set).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
See the comments on the fundamental block size above.

@end enumerate
@c -----------------------------------------------------------------------------
@node _stklen, stpcpy, statvfs, Alphabetical List
@unnumberedsec _stklen
@c From file ./crt0/crt0.txh
@vindex _stklen
@subheading Syntax

@example
extern int _stklen;
@end example

@subheading Description

This variable sets the minimum stack length that the program requires. 
Note that the stack may be much larger than this.  This value should be
set statically, as it is only used at startup. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
int _stklen = 256000;
@end example

@c -----------------------------------------------------------------------------
@node stpcpy, stpncpy, _stklen, Alphabetical List
@unnumberedsec stpcpy
@c From file ./compat/string/stpcpy.txh
@findex stpcpy
@subheading Syntax

@example
#include <string.h>

char *stpcpy(char *_dest, const char *_src);
@end example

@subheading Description

Like @code{strcpy} (@pxref{strcpy}), but return value different.

@subheading Return Value

Returns a pointer to the trailing NUL in @var{dest}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node stpncpy, strcasecmp, stpcpy, Alphabetical List
@unnumberedsec stpncpy
@c From file ./compat/string/stpncpy.txh
@findex stpncpy
@subheading Syntax

@example
#include <string.h>

char *stpncpy(char *_dest, const char *_src, size_t _n);
@end example

@subheading Description

Copies exactly @var{_n} characters from @var{_src} to @var{_dest}.
If need be, @var{_dest} is padded with zeros to make @var{_n} characters.
Like @code{strncpy} (@pxref{strncpy}), but return value different.

@subheading Return Value

Returns a pointer to the character following the last nonzero written.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node strcasecmp, strcat, stpncpy, Alphabetical List
@unnumberedsec strcasecmp
@c From file ./compat/string/strcasec.txh
@findex strcasecmp
@subheading Syntax

@example
#include <string.h>

int strcasecmp(const char *s1, const char *s2);
@end example

@subheading Description

This function compares the two strings, disregarding case.

@subheading Return Value

Zero if they're the same, nonzero if different, the sign indicates
"order". 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
if (strcasecmp(arg, "-i") == 0)
  do_include();
@end example

@c -----------------------------------------------------------------------------
@node strcat, strchr, strcasecmp, Alphabetical List
@unnumberedsec strcat
@c From file ./ansi/string/strcat.txh
@findex strcat
@subheading Syntax

@example
#include <string.h>

char *strcat(char *s1, const char *s2);
@end example

@subheading Description

This function concatenates @var{s2} to the end of @var{s1}.

@subheading Return Value

@var{s1}

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
char buf[100] = "hello";
strcat(buf, " there");
@end example

@c -----------------------------------------------------------------------------
@node strchr, strcmp, strcat, Alphabetical List
@unnumberedsec strchr
@c From file ./ansi/string/strchr.txh
@findex strchr
@subheading Syntax

@example
#include <string.h>

char *strchr(const char *s, int c);
@end example

@subheading Description

This function returns a pointer to the first occurrence of @var{c} in
@var{s}.  Note that if @var{c} is @code{NULL}, this will return a
pointer to the end of the string. 

@subheading Return Value

A pointer to the character, or @code{NULL} if it wasn't found. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
char *slash = strchr(filename, '/');
@end example

@c -----------------------------------------------------------------------------
@node strcmp, strcoll, strchr, Alphabetical List
@unnumberedsec strcmp
@c From file ./ansi/string/strcmp.txh
@findex strcmp
@subheading Syntax

@example
#include <string.h>

int strcmp(const char *s1, const char *s2);
@end example

@subheading Description

This function compares @var{s1} and @var{s2}.

@subheading Return Value

Zero if the strings are equal, a positive number if @var{s1} comes after
@var{s2} in the ASCII collating sequence, else a negative number. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
if (strcmp(arg, "-i") == 0)
  do_include();
@end example

@c -----------------------------------------------------------------------------
@node strcoll, strcpy, strcmp, Alphabetical List
@unnumberedsec strcoll
@c From file ./ansi/string/strcoll.txh
@findex strcoll
@subheading Syntax

@example
#include <string.h>

int strcoll(const char *s1, const char *s2);
@end example

@subheading Description

This function compares @var{s1} and @var{s2}, using the collating
sequences from the current locale. 

@subheading Return Value

Zero if the strings are equal, a positive number if @var{s1} comes after
@var{s2} in the collating sequence, else a negative number. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
while (strcoll(var, list[i]) < 0)
  i++;
@end example

@c -----------------------------------------------------------------------------
@node strcpy, strcspn, strcoll, Alphabetical List
@unnumberedsec strcpy
@c From file ./ansi/string/strcpy.txh
@findex strcpy
@subheading Syntax

@example
#include <string.h>

char *strcpy(char *s1, const char *s2);
@end example

@subheading Description

This function copies @var{s2} into @var{s1}.

@subheading Return Value

@var{s1}

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
char buf[100];
strcpy(buf, arg);
@end example

@c -----------------------------------------------------------------------------
@node strcspn, strdup, strcpy, Alphabetical List
@unnumberedsec strcspn
@c From file ./ansi/string/strcspn.txh
@findex strcspn
@subheading Syntax

@example
#include <string.h>

size_t strcspn(const char *s1, const char *set);
@end example

@subheading Description

This function finds the first character in @var{s1} that matches any
character in @var{set}.  Note that the @code{NULL} bytes at the end of
each string counts, so you'll at least get a pointer to the end of the
string if nothing else. 

@subheading Return Value

The index of the found character.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
int i = strcspn(command, "<>|");
if (command[i])
  do_redirection();
@end example

@c -----------------------------------------------------------------------------
@node strdup, strerror, strcspn, Alphabetical List
@unnumberedsec strdup
@c From file ./compat/string/strdup.txh
@findex strdup
@subheading Syntax

@example
#include <string.h>

char * strdup (const char *source);
@end example

@subheading Description

Returns a newly allocated area of memory that contains a duplicate of
the string pointed to by @var{source}.  The memory returned by this
call must be freed by the caller.

@subheading Return Value

Returns the newly allocated string, or @var{NULL} if there
is no more memory.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char *foo()
@{
  return strdup("hello");
@}
@end example

@c -----------------------------------------------------------------------------
@node strerror, strerror_r, strdup, Alphabetical List
@unnumberedsec strerror
@c From file ./ansi/string/strerror.txh
@findex strerror
@subheading Syntax

@example
#include <string.h>

char *strerror(int error);
@end example

@subheading Description

This function returns a string that describes the @var{error}. 

@subheading Return Value

A pointer to a static string that should not be modified or free'd. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
if (f=fopen("foo", "r") == 0)
  printf("Error! %s: %s\n", "foo", strerror(errno));
@end example

@c -----------------------------------------------------------------------------
@node strerror_r, strftime, strerror, Alphabetical List
@unnumberedsec strerror_r
@c From file ./posix/string/strerr_r.txh
@findex strerror_r
@subheading Syntax

@example
#include <string.h>

int strerror_r(int error, char *strerrbuf, size_t buflen);
@end example

@subheading Description

This function fills the @var{strerrbuf} of length @var{buflen} with a
string that describes the @var{error}.  

@subheading Return Value

0 if successful or @code{ERANGE} if @var{buflen} is too small.  

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
f=fopen("foo", "r");
if( f == NULL )
@{
  char buf[1];
  int error_again;
	
  error_again = strerror_r(errno, buf, 1);
  if( error_again )
  @{
    char buf2[1024];
    int error_again2;

    error_again2 = strerror_r(errno, buf2, 1024);
    if( error_again2 )
    @{
      printf("Error while trying to decode error from calling strerror_r(). I give up!\n"
      "Calling strerror: '%s'\n", strerror(error_again2));
    @}
    printf("Error while trying to decode error from calling fopen(): '%s'\n", 
	buf2);
  @}
  else
  @{
    printf("Error from fopen(): %s\n", buf);
  @}
@end example

@c -----------------------------------------------------------------------------
@node strftime, stricmp, strerror_r, Alphabetical List
@unnumberedsec strftime
@c From file ./ansi/time/strftime.txh
@findex strftime
@subheading Syntax

@example
#include <time.h>

size_t strftime(char *buf, size_t n, const char *format,
                const struct tm *time_info);
@end example

@subheading Description

This function formats the time data in @var{time_info} according to the
given @var{format} and stores it in @var{buf}, not exceeding @var{n}
bytes.

The format string is like @code{printf} in that any character other than
@code{%} is added to the output string, and for each character following
a @code{%} a pattern is added to the string as follows, with the
examples as if the time was Friday, October 1, 1993, at 03:30:34 PM EDT:

@table @code

@item %A

The full weekday name (@code{Friday})

@item %a

The abbreviated weekday name (@code{Fri})

@item %B

The full month name (@code{October})

@item %b
@itemx %h

The abbreviated month name (@code{Oct})

@item %C

The century number (year/100) as a 2-digit integer (@code{19})

@item %c

Short for @code{%m/%d/%y %H:%M:%S} (@code{10/01/93 15:30:34})

@item %D

Short for @code{%m/%d/%y} (@code{10/01/93})

@item %d

The day of the month (1-31), zero padded to two characters (@code{02})

@item %Ex
In some locales, the @code{E} modifier selects alternative representations
of certain conversion specifiers @code{x}.  But in the "C" locale supported
by djgpp, it is ignored, and treated as @code{%x}.  E.G.: @code{%EC} will be
mapped to @code{%C}.

@item %e

The day of the month (1-31), blank padded to two characters (@code{ 2})

@item %F

The ISO 8601:2000 date format, in the form @code{%Y-%m-%d} (@code{1993-10-01})

@item %G

The ISO 8601:2000 standard week-based year with century as a decimal number.
The 4-digit year corresponding to the ISO week number (see @code{%V}).  This has the
same format and value as @code{%Y}, except that if the ISO week number belongs to the
previous or next year, that year is used instead (@code{1993})

@item %g

Like @code{%G}, but without century, i.e., with a 2-digit year (@code{93})

@item %H

The hour (0-24), zero padded to two characters (@code{15})

@item %I

The hour (1-12), zero padded to two characters (@code{03})

@item %j

The Julian day (1-366), zero padded to three characters (@code{275})

@item %k

The hour (0-24), space padded to two characters (@code{15})

@item %l

The hour (1-12), space padded to two characters(@code{ 3})

@item %M

The minutes (0-59), zero padded to two characters (@code{30})

@item %m

The month (1-12), zero padded to two characters (@code{10})

@item %n

A newline (@code{\n})

@item %Ox
In some locales, the @code{O} modifier selects alternative digit characters
for certain conversion specifiers @code{x}.  But in the "C" locale supported
by djgpp, it is ignored, and treated as @code{%x}.  E.G.: @code{%OH} will be
mapped to @code{%H}.

@item %p

AM or PM (@code{PM})

@item %P

Like @code{%p} but in lowercase: am or pm (@code{pm})

@item %R

Short for @code{%H:%M} (@code{15:30})

@item %r

Short for @code{%I:%M:%S %p} (@code{03:30:35 PM})

@item %S

The seconds (0-60), zero padded to two characters (@code{35})

@item %s

The seconds since the Epoch, i.e., since 1970-01-01 00:00:00 UTC (@code{749489433})

@item %T

Short for @code{%H:%M:%S} (@code{15:30:35})

@item %t

A tab (@code{\t})

@item %U

The week of the year (0-53), with the first week defined by the first Sunday of
the year, and earlier days are in week 0, zero padded to two characters (@code{39})

@item %u

The day of the week (1-7), Monday being 1 (@code{6})

@item %V

The ISO week of the year (01-53), where weeks start on Monday, with the first
week defined by the first Thursday of the year, zero padded to two characters (@code{39})

@item %W

The week of the year (0-53), with the first week defined by the first Monday of
the year, and earlier days are in week 0, zero padded to two characters (@code{39})

@item %w

The day of the week (0-6), Sunday being 0 (@code{5})

@item %x

Date represented according to the current locale.

@item %X

Time represented according to the current locale.

@item %y

The year (00-99) of the century (@code{93})

@item %Y

The year, zero padded to four digits (@code{1993})

@item %Z

The timezone abbreviation (@code{EDT})

@item %z

The time-zone as hour offset from GMT in the ISO 8601:2000 standard format (@code{+hhmm} or @code{-hhmm}),
or by no characters if no timezone is determinable.  Required to emit RFC 822-conformant
dates using @code{%a, %d %b %Y  %H:%M:%S  %z} (@code{Fri, 01 Oct 1993  03:30:34  -0500})

@item %+

The date and time in date(1) format.  Not supported in djgpp

@item %%

A percent symbol (@code{%})

@end table


The following flag characters, preceding the conversion specifier characters described
above, are permitted:

@table @code

@item _

(underscore) Pad a numeric result string with spaces


@item -

(dash) Do not pad a numeric result string

@item 0

Pad a numeric result string with zeros even if the conversion specifier character
uses space-padding by default

@item ^

Convert alphabetic characters in result string to upper case

@item #

Swap the case of the result string.  (This flag only works with certain conversion specifier characters,
and of these, it is only really useful with %Z).

@end table

@subheading Return Value

The number of characters stored.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
time_t now = time (NULL);
struct tm *t = localtime (&now);
char buf[100];
/* Print today's date e.g. "January 31, 2001".  */
strftime (buf, 100, "%B %d, %Y", t);
@end example

@c -----------------------------------------------------------------------------
@node stricmp, strlcat, strftime, Alphabetical List
@unnumberedsec stricmp
@c From file ./compat/string/stricmp.txh
@findex stricmp
@subheading Syntax

@example
#include <string.h>

int stricmp(const char *s1, const char *s2);
@end example

@subheading Description

This function compares the two strings, disregarding case.

@subheading Return Value

Zero if they're the same, nonzero if different, the sign indicates
"order". 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
if (stricmp(arg, "-i") == 0)
  do_include();
@end example
@c -----------------------------------------------------------------------------
@node strlcat, strlcpy, stricmp, Alphabetical List
@unnumberedsec strlcat
@c From file ./compat/string/strlcat.txh
@findex strlcat
@subheading Syntax

@example
#include <string.h>

size_t strlcat (char *dest, const char *src, size_t size);
@end example

@subheading Description

Concatenate characters from @var{src} to @var{dest} and nul-terminate
the resulting string.  As much of @var{src} is copied into @var{dest}
as there is space for.

@var{size} should be the size of the destination string buffer @var{dest}
plus the space for the nul-terminator.  @var{size} may be computed
in many cases using the @code{sizeof} operator.

@code{strlcat} may be used as a less ambiguous alternative
to @code{strncat} (@pxref{strncat}).  @code{strlcat} returns
the length of the concatenated string whether or not it was possible
to copy it all --- this makes it easier to calculate
the required buffer size.

If @var{dest} is not nul-terminated, then @var{dest} is not modified.

@code{strlcat} will not examine more than @var{size} characters
of @var{dest}.  This is to avoid overrunning the buffer @var{dest}.

If @var{dest} and @var{src} are overlapping buffers, the behavior
is undefined.  One possible result is a buffer overrun - accessing
out-of-bounds memory.

The original OpenBSD paper describing @code{strlcat}
and @code{strlcpy} (@pxref{strlcpy}) is available on the web:
@uref{http://www.openbsd.org/papers/strlcpy-paper.ps}.

@subheading Return Value

The length of the string that @code{strlcat} tried to create is returned,
whether or not @code{strlcat} could store it in @var{dest}.  If all
of @var{src} was concatenated to @var{dst}, the return value will be less
than @var{size}.

If @var{dest} is not nul-terminated, then @code{strlcat} will consider
@var{dest} to be @var{size} in length and return @var{size} plus
the length of @var{src}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

The following example shows how you can check that
the destination string buffer was large enough to store
the source string concatenated to the destination string.
In this case @code{somestring} is truncated, when it is concatenated
to @code{buf}.

@example
const char somestring[] = "bar";
char buf[5] = "foo";

if (strlcat(buf, somestring, sizeof(buf)) >= sizeof(buf))
  puts("somestring was truncated, when concatenating to buf.");
@end example
@c -----------------------------------------------------------------------------
@node strlcpy, strlen, strlcat, Alphabetical List
@unnumberedsec strlcpy
@c From file ./compat/string/strlcpy.txh
@findex strlcpy
@subheading Syntax

@example
#include <string.h>

size_t strlcpy (char *dest, const char *src, size_t size);
@end example

@subheading Description

Copy characters from @var{src} to @var{dest} and nul-terminate
the resulting string.  Up to @code{@var{size} - 1} characters are
copied to @var{dest}.

@var{size} should be the size of the destination string buffer @var{dest}
plus the space for the nul-terminator.  @var{size} may be computed
in many cases using the @code{sizeof} operator.

@code{strlcpy} is a less ambiguous version of @code{strncpy}
(@pxref{strncpy}).  Unlike @code{strncpy}, @code{strlcpy} @emph{always}
nul-terminates the destination @var{dest} for non-zero sizes @var{size}.
@code{strlcpy} returns the length of the string whether or not
it was possible to copy it all --- this makes it easier to calculate
the required buffer size.

If @var{dest} and @var{src} are overlapping buffers, the behavior
is undefined.  One possible result is a buffer overrun - accessing
out-of-bounds memory.

The original OpenBSD paper describing @code{strlcpy}
and @code{strlcat} (@pxref{strlcat}) is available on the web:
@uref{http://www.openbsd.org/papers/strlcpy-paper.ps}.

@subheading Return Value

The length of the string that @code{strlcpy} tried to create is returned,
whether or not @code{strlcpy} could store it in @var{dest}.  If all
of @var{src} was copied, the return value will be less than @var{size}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

The following example shows how you can check that
the destination string buffer was large enough to store the source string.
In this case @code{somestring} is truncated to fit into @code{buf}.

@example
const char somestring[] = "foo";
char buf[3];

if (strlcpy(buf, somestring, sizeof(buf)) >= sizeof(buf))
  puts("somestring was truncated, when copying to buf.");
@end example
@c -----------------------------------------------------------------------------
@node strlen, strlwr, strlcpy, Alphabetical List
@unnumberedsec strlen
@c From file ./ansi/string/strlen.txh
@findex strlen
@subheading Syntax

@example
#include <string.h>

size_t strlen(const char *string);
@end example

@subheading Description

This function returns the number of characters in @var{string}.

@subheading Return Value

The length of the string.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
if (strlen(fname) > PATH_MAX)
  invalid_file(fname);
@end example

@c -----------------------------------------------------------------------------
@node strlwr, strncasecmp, strlen, Alphabetical List
@unnumberedsec strlwr
@c From file ./compat/string/strlwr.txh
@findex strlwr
@subheading Syntax

@example
#include <string.h>

char *strlwr(char *string);
@end example

@subheading Description

This function replaces all upper case letters in @var{string} with lower
case letters. 

@subheading Return Value

The string.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char buf[100] = "Hello";
strlwr(buf);
@end example

@c -----------------------------------------------------------------------------
@node strncasecmp, strncat, strlwr, Alphabetical List
@unnumberedsec strncasecmp
@c From file ./compat/string/strncase.txh
@findex strncasecmp
@subheading Syntax

@example
#include <string.h>

int strncasecmp(const char *s1, const char *s2, size_t max);
@end example

@subheading Description

This function compares @var{s1} and @var{s2}, ignoring case, up to a
maximum of @var{max} characters. 

@subheading Return Value

Zero if the strings are equal, a positive number if @var{s1} comes after
@var{s2} in the ASCII collating sequense, else a negative number. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
if (strncasecmp(foo, "-i", 2) == 0)
  do_include();
@end example

@c -----------------------------------------------------------------------------
@node strncat, strncmp, strncasecmp, Alphabetical List
@unnumberedsec strncat
@c From file ./ansi/string/strncat.txh
@findex strncat
@subheading Syntax

@example
#include <string.h>

char *strncat(char *s1, const char *s2, size_t max);
@end example

@subheading Description

This function concatenates up to @var{max} characters of @var{s2} to the
end of @var{s1}.

@subheading Return Value

@var{s1}

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
strncat(fname, extension, 4);
@end example

@c -----------------------------------------------------------------------------
@node strncmp, strncpy, strncat, Alphabetical List
@unnumberedsec strncmp
@c From file ./ansi/string/strncmp.txh
@findex strncmp
@subheading Syntax

@example
#include <string.h>

int strncmp(const char *s1, const char *s2, size_t max);
@end example

@subheading Description

This function compares up to @var{max} characters of @var{s1} and @var{s2}.

@subheading Return Value

Zero if the strings are equal, a positive number if @var{s1} comes after
@var{s2} in the ASCII collating sequence, else a negative number. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
if (strncmp(arg, "-i", 2) == 0)
  do_include();
@end example

@c -----------------------------------------------------------------------------
@node strncpy, strndup, strncmp, Alphabetical List
@unnumberedsec strncpy
@c From file ./ansi/string/strncpy.txh
@findex strncpy
@subheading Syntax

@example
#include <string.h>

char *strncpy(char *s1, const char *s2, size_t max);
@end example

@subheading Description

This function copies up to @var{max} characters of @var{s2} into @var{s1}.

@subheading Return Value

@var{s1}

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
char buf[100];
strncpy(buf, arg, 99);
@end example

@c -----------------------------------------------------------------------------
@node strndup, strnicmp, strncpy, Alphabetical List
@unnumberedsec strndup
@c From file ./posix/string/strndup.txh
@findex strndup
@subheading Syntax

@example
#include <string.h>

char * strndup (const char *source, size_t size);
@end example

@subheading Description

Returns a newly allocated area of memory that contains a duplicate of at most
@var{size} of characters of the string pointed to by @var{source}.  The memory
returned by this call must be freed by the caller.

@subheading Return Value

Returns the newly allocated string, or @var{NULL} if there
is no more memory.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
char *foo()
@{
  return strndup("hello world", 5);
@}
@end example

@c -----------------------------------------------------------------------------
@node strnicmp, strnlen, strndup, Alphabetical List
@unnumberedsec strnicmp
@c From file ./compat/string/strnicmp.txh
@findex strnicmp
@subheading Syntax

@example
#include <string.h>

int strnicmp(const char *s1, const char *s2, size_t max);
@end example

@subheading Description

This function compares @var{s1} and @var{s2}, ignoring case, up to a
maximum of @var{max} characters. 

@subheading Return Value

Zero if the strings are equal, a positive number if @var{s1} comes after
@var{s2} in the ASCII collating sequence, else a negative number. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
if (strnicmp(foo, "-i", 2) == 0)
  do_include();
@end example
@c -----------------------------------------------------------------------------
@node strnlen, strpbrk, strnicmp, Alphabetical List
@unnumberedsec strnlen
@c From file ./posix/string/strnlen.txh
@findex strnlen
@subheading Syntax

@example
#include <string.h>

size_t strnlen(const char *string, size_t size);
@end example

@subheading Description

This function returns the number of characters in @var{string},
but at most @var{size}.  In doing this, the function looks only
at the first @var{size} characters at @var{string} and never
beyond @var{string} + @var{size}.

@subheading Return Value

The length of the string.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
size_t max_string_length = 10000;

if (strnlen(fname, max_string_length) > PATH_MAX)
  invalid_file(fname);
@end example

@c -----------------------------------------------------------------------------
@node strpbrk, strrchr, strnlen, Alphabetical List
@unnumberedsec strpbrk
@c From file ./ansi/string/strpbrk.txh
@findex strpbrk
@subheading Syntax

@example
#include <string.h>

char *strpbrk(const char *s1, const char *set);
@end example

@subheading Description

This function finds the first character in @var{s1} that matches any
character in @var{set}.

@subheading Return Value

A pointer to the first match, or @code{NULL} if none are found.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
if (strpbrk(command, "<>|"))
  do_redirection();
@end example

@c -----------------------------------------------------------------------------
@node strrchr, strsep, strpbrk, Alphabetical List
@unnumberedsec strrchr
@c From file ./ansi/string/strrchr.txh
@findex strrchr
@subheading Syntax

@example
#include <string.h>

char *strrchr(const char *s1, int c);
@end example

@subheading Description

This function finds the last occurrence of @code{c} in @code{s1}.

@subheading Return Value

A pointer to the last match, or @code{NULL} if the character isn't in
the string. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
char *last_slash = strrchr(filename, '/');
@end example

@c -----------------------------------------------------------------------------
@node strsep, strspn, strrchr, Alphabetical List
@unnumberedsec strsep
@c From file ./compat/string/strsep.txh
@findex strsep
@subheading Syntax

@example
#include <string.h>

char *strsep(char **stringp, char *delim);
@end example

@subheading Description

This function retrieves the next token from the given string, where
@var{stringp} points to a variable holding, initially, the start of the
string.  Tokens are delimited by a character from @var{delim}.  Each
time the function is called, it returns a pointer to the next token, and
sets *@var{stringp} to the next spot to check, or @code{NULL}. 

@subheading Return Value

The next token, or NULL.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
main()
@{
  char *buf = "Hello  there,stranger";
  char **bp = &buf;
  char *tok;
  while (tok = strsep(bp, " ,"))
    printf("tok = `%s'\n", tok);
@}

tok = `Hello'
tok = `'
tok = `there'
tok = `stranger'
@end example

@c -----------------------------------------------------------------------------
@node strspn, strstr, strsep, Alphabetical List
@unnumberedsec strspn
@c From file ./ansi/string/strspn.txh
@findex strspn
@subheading Syntax

@example
#include <string.h>

size_t strspn(const char *s1, const char *set);
@end example

@subheading Description

This function finds the first character in @var{s1} that does not match
any character in @var{set}.  Note that the @code{NULL} bytes at the end
of @var{s1} counts, so you'll at least get a pointer to the end of the
string if nothing else. 

@subheading Return Value

The index of the found character.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
int i = strspn(entry, " \t\b");
if (entry[i])
  do_something();
@end example

@c -----------------------------------------------------------------------------
@node strstr, strtod, strspn, Alphabetical List
@unnumberedsec strstr
@c From file ./ansi/string/strstr.txh
@findex strstr
@subheading Syntax

@example
#include <string.h>

char *strstr(const char *s1, const char *s2);
@end example

@subheading Description

This function finds the first occurrence of @var{s2} in @var{s1}. 

@subheading Return Value

A pointer within @var{s1}, or @code{NULL} if @var{s2} wasn't found.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
if (strstr(command, ".exe"))
  do_exe();
@end example

@c -----------------------------------------------------------------------------
@node strtod, strtof, strstr, Alphabetical List
@unnumberedsec strtod
@c From file ./ansi/stdlib/strtod.txh
@findex strtod
@subheading Syntax

@example
#include <stdlib.h>

double strtod(const char *s, char **endp);
@end example

@subheading Description

This function converts as many characters of @var{s} that look like a
floating point number into that number.  The floating point number may
also take the form of a hex floating point number (case-insensitively)
like this [+|-]0xH.HHHp[+|-]DDD.  It also recognises (case-insensitively)
``Inf'', ``Infinity'', ``NaN'', ``NaN(@var{optional decimal-number})'',
``NaN(@var{optional octal-number})'' and ``NaN(@var{optional hex-number})''.
If @var{endp} is not a null pointer, a pointer to the first unconverted
character will be stored in the location pointed to by @var{endp}.  

@subheading Return Value

The value represented by @var{s}.

If @var{s} is ``Inf'' or ``Infinity'', with any variations of
case and optionally prefixed with ``+'' or ``-'', the return value is
@code{INFINITY} (if no prefix or a ``+'' prefix) or @code{-INFINITY}
(if the prefix is ``-'').

If @var{s} is ``NaN'' or ``NaN()'', with any variations of case
and optionally prefixed with ``+'' or ``-'', the return value is
@code{(double)NAN}.  If the prefix is ``-'' the sign bit in the NaN
will be set to 1.

If @var{s} is ``NaN(@var{decimal-number})'', ``NaN(@var{octal-number})''
or ``NaN(@var{hex-number})'', with any variations of
case and optionally prefixed with ``+'' or ``-'', the return value is
a NaN with the mantissa bits set to the lower 52 bits
of @var{decimal-number}, @var{octal-number} or @var{hex-number}
(the mantissa for doubles consists of 52 bits).  Use
at most 16 hexadecimal digits in @var{hex-number} or the internal
conversion will overflow, which results in a mantissa with all bits
set.  If the bit pattern given is 0 (which won't work as a
representation of a NaN) @code{(double)NAN} will be returned.  If the
prefix is ``-'' the sign bit in the NaN will be set to 1.  Testing
shows that SNaNs might be converted into QNaNs (most significant bit
will be set in the mantissa).  

If a number represented by @var{s} doesn't fit into the range of values
representable by the type @code{double}, the function returns either
@code{-HUGE_VAL} (if @var{s} begins with the character @code{-}) or
@code{+HUGE_VAL}, and sets @code{errno} to @code{ERANGE}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99 (see note 1)
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable

@noindent
Notes:

@enumerate
@item
Support for ``Inf'', ``Infinity'', ``NaN'' and
``NaN(@dots{})'' was standardised in ANSI C99.

@end enumerate

@subheading Example

@example
char buf[] = "123ret";
char buf2[] = "0x123ret";
char buf3[] = "NAN(123)";
char buf4[] = "NAN(0x123)";
char buf5[] = "0x1234567.89ABCDefP+123";
char *bp;
double x, x2, x3, x4;

x = strtod(buf, &bp);
x2 = strtod(buf2, &bp);
x3 = strtod(buf3, &bp);
x4 = strtod(buf4, &bp);
x5 = strtod(buf5, &bp);
@end example

@c -----------------------------------------------------------------------------
@node strtof, strtoimax, strtod, Alphabetical List
@unnumberedsec strtof
@c From file ./c99/stdlib/strtof.txh
@findex strtof
@subheading Syntax

@example
#include <stdlib.h>

float strtof(const char *s, char **endp);
@end example

@subheading Description

This function converts as many characters of @var{s} that look like a
floating point number into that number.  The floating point number may
also take the form of a hex floating point number (case-insensitively)
like this [+|-]0xH.HHHp[+|-]DDD.  It also recognises (case-insensitively)
``Inf'', ``Infinity'', ``NaN'', ``NaN(@var{optional decimal-number})'',
``NaN(@var{optional octal-number})'' and ``NaN(@var{optional hex-number})''.
If @var{endp} is not a null pointer, a pointer to the first unconverted
character will be stored in the location pointed to by @var{endp}.  

@subheading Return Value

The value represented by @var{s}.

If @var{s} is ``Inf'' or ``Infinity'', with any variations of case and
optionally prefixed with ``+'' or ``-'', the return value is
@code{INFINITY} (if no prefix or a ``+'' prefix) or @code{-INFINITY}
(if the prefix is ``-'').

If @var{s} is ``NaN'' or ``NaN()'', with any variations of case and
optionally prefixed with ``+'' or ``-'', the return value is
@code{NAN}.  If the prefix is ``-'' the sign bit in the NaN will be
set to 1.

If @var{s} is ``NaN(@var{decimal-number})'', ``NaN(@var{octal-number})''
or ``NaN(@var{hex-number})'', with any variations of case
and optionally prefixed with ``+'' or ``-'', the return value is a NaN
with the mantissa bits set to the lower 23 bits
of @var{decimal-number}, @var{octal-number} or @var{hex-number}
(the mantissa for floats consists of 23 bits).  Use at most 8
hexadecimal digits in @var{hex-number} or the internal conversion will
overflow, which results in a mantissa with all bits set.  If the bit
pattern given is 0 (which won't work as a representation of a NaN)
@code{NAN} will be returned.  If the prefix is ``-'' the sign bit in
the NaN will be set to 1.  Testing shows that SNaNs might be converted
into QNaNs (most significant bit will be set in the mantissa).

If a number represented by @var{s} doesn't fit into the range of values
representable by the type @code{float}, the function returns either
@code{-HUGE_VALF} (if @var{s} begins with the character @code{-}) or
@code{+HUGE_VALF}, and sets @code{errno} to @code{ERANGE}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99 (see note 1); not C89
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable

@noindent
Notes:

@enumerate
@item
Support for ``Inf'', ``Infinity'', ``NaN'' and
``NaN(@dots{})'' was standardised in ANSI C99.

@end enumerate

@subheading Example

@example
char buf[] = "123ret";
char buf2[] = "0x123ret";
char buf3[] = "NAN(123)";
char buf4[] = "NAN(0x123)";
char buf5[] = "0x1234567.89ABCDefP+12";
char *bp;
float x, x2, x3, x4;

x = strtof(buf, &bp);
x2 = strtof(buf2, &bp);
x3 = strtof(buf3, &bp);
x4 = strtof(buf4, &bp);
x5 = strtod(buf5, &bp);
@end example
@c -----------------------------------------------------------------------------
@node strtoimax, strtok, strtof, Alphabetical List
@unnumberedsec strtoimax
@c From file ./c99/inttypes/strimax.txh
@findex strtoimax
@subheading Syntax

@example
#include <inttypes.h>

intmax_t strtoimax (const char *s, char **endp, int base)
@end example

@subheading Description

This function converts as much of @var{s} as looks like an appropriate
number into the value of that number, and sets @var{*endp} to point to
the first unused character.

The @var{base} argument indicates what base the digits (or letters)
should be treated as.  If @var{base} is zero, the base is determined by
looking for @code{0x}, @code{0X}, or @code{0} as the first part of the
string, and sets the base used to 16, 16, or 8 if it finds one.  The
default base is 10 if none of those prefixes are found.

@subheading Return Value

The value.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable


@subheading Example

@example
printf("Enter a number: "); fflush(stdout);
gets(buf);
char *bp;
printf("The value is %" PRIdMAX "\n", strtoimax(buf, &bp, 0));
@end example
@c -----------------------------------------------------------------------------
@node strtok, strtok_r, strtoimax, Alphabetical List
@unnumberedsec strtok
@c From file ./ansi/string/strtok.txh
@findex strtok
@subheading Syntax

@example
#include <string.h>

char *strtok(char *s1, const char *s2);
@end example

@subheading Description

This function retrieves tokens from @var{s1} which are delimited by
characters from @var{s2}.

To initiate the search, pass the string to be searched as @var{s1}.  For
the remaining tokens, pass @code{NULL} instead. 

@subheading Return Value

A pointer to the token, or @code{NULL} if no more are found.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
#include <stdio.h>
#include <string.h>

int main(void)
@{
  char buf[] = "Hello there, stranger";
  char *tok;
  for (tok = strtok(buf, " ,");
       tok;
       tok=strtok(0, " ,"))
    printf("tok = `%s'\n", tok);

  return 0;
@}

tok = `Hello'
tok = `there'
tok = `stranger'
@end example

@c -----------------------------------------------------------------------------
@node strtok_r, strtol, strtok, Alphabetical List
@unnumberedsec strtok_r
@c From file ./posix/string/strtok_r.txh
@findex strtok_r
@subheading Syntax

@example
#include <string.h>

char *strtok_r(char *s1, const char *s2, char **s3);
@end example

@subheading Description

This function retrieves tokens from @var{s1} which are delimited by
characters from @var{s2}.  It uses @var{s3} to track how far in
@var{s1} the search has progressed.  

To initiate the search, pass the string to be searched as @var{s1}.  For
the remaining tokens, pass @code{NULL} instead.  

@subheading Return Value

A pointer to the token, or @code{NULL} if no more are found.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
#include <stdio.h>
#include <string.h>

int main(void)
@{
  char buf[] = "Hello there, stranger";
  char *tok, *where;
  for (tok = strtok(buf, " ,", &where);
       tok;
       tok=strtok(NULL, " ,", &where))
    printf("tok = `%s'\n", tok);

  return 0;
@}

tok = `Hello'
tok = `there'
tok = `stranger'
@end example

@c -----------------------------------------------------------------------------
@node strtol, strtold, strtok_r, Alphabetical List
@unnumberedsec strtol
@c From file ./ansi/stdlib/strtol.txh
@findex strtol
@subheading Syntax

@example
#include <stdlib.h>

long strtol(const char *s, char **endp, int base);
@end example

@subheading Description

This function converts as much of @var{s} as looks like an appropriate
number into the value of that number.  If @var{endp} is not a null
pointer, @var{*endp} is set to point to the first unused character. 

The @var{base} argument indicates what base the digits (or letters)
should be treated as.  If @var{base} is zero, the base is determined by
looking for @code{0x}, @code{0X}, or @code{0} as the first part of the
string, and sets the base used to 16, 16, or 8 if it finds one.  The
default base is 10 if none of those prefixes are found.

@subheading Return Value

The value.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
printf("Enter a number: "); fflush(stdout);
gets(buf);
char *bp;
printf("The value is %d\n", strtol(buf, &bp, 0));
@end example

@c -----------------------------------------------------------------------------
@node strtold, _strtold, strtol, Alphabetical List
@unnumberedsec strtold
@c From file ./ansi/stdlib/strtold.txh
@findex strtold
@subheading Syntax

@example
#include <stdlib.h>

long double strtold(const char *s, char **endp);
@end example

@subheading Description

This function converts as many characters of @var{s} that look like a
floating point number into that number.  The floating point number may
also take the form of a hex floating point number (case-insensitively)
like this [+|-]0xH.HHHp[+|-]DDD.  It also recognises (case-insensitively)
``Inf'', ``Infinity'', ``NaN'', ``NaN(@var{optional decimal-number})'',
``NaN(@var{optional octal-number})'' and ``NaN(@var{optional hex-number})''.
If @var{endp} is not a null pointer, a pointer to the first unconverted
character will be stored in the location pointed to by @var{endp}.  

@subheading Return Value

The value represented by @var{s}. 

If @var{s} is ``Inf'' or ``Infinity'', with any variations of case and
optionally prefixed with ``+'' or ``-'', the return value is
@code{INFINITY} (if no prefix or a ``+'' prefix) or @code{-INFINITY}
(if the prefix is ``-'').  

If @var{s} is ``NaN'' or ``NaN()'', with any variations of case and
optionally prefixed with ``+'' or ``-'', the return value is
@code{(long double)NAN}.  If the prefix is ``-'' the sign bit in the
NaN will be set to 1.  

If @var{s} is ``NaN(@var{decimal-number})'', ``NaN(@var{octal-number})''
or ``NaN(@var{hex-number})'', with any variations of case
and optionally prefixed with ``+'' or ``-'', the return value is a NaN
with the mantissa bits set to the lower 63 bits
of @var{decimal-number}, @var{octal-number} or @var{hex-number}
and the most significant bit to 1 (the mantissa for long 
doubles consists of 64 bits where the most significant bit is the
integer bit which must be set for NaNs).  Use at most 16 hexadecimal
digits in @var{hex-number} or the internal conversion will overflow,
which results in a mantissa with all bits set.  If the bit pattern
given is 0 (which won't work as a representation of a NaN) @code{(long
double)NAN} will be returned.  If the prefix is ``-'' the sign bit in
the NaN will be set to 1.  Testing shows that SNaNs might be converted
into QNaNs (the second most significant bit will be set in the
mantissa).  

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99 (see note 1); not C89
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable

@noindent
Notes:

@enumerate
@item
Support for ``Inf'', ``Infinity'', ``NaN'' and
``NaN(@dots{})'' was standardised in ANSI C99.

@end enumerate

@subheading Example

@example
char buf[] = "123ret";
char buf2[] = "0x123ret";
char buf3[] = "NAN(123)";
char buf4[] = "NAN(0x123)";
char buf5[] = "0x1234567.89abcdefP+1234";
char *bp;
long double x, x2, x3, x4;

x = strtold(buf, &bp);
x2 = strtold(buf2, &bp);
x3 = strtold(buf3, &bp);
x4 = strtold(buf4, &bp);
x5 = strtold(buf5, &bp);
@end example
@c -----------------------------------------------------------------------------
@node _strtold, strtoll, strtold, Alphabetical List
@unnumberedsec _strtold
@c From file ./ansi/stdlib/strtold.txh
@findex _strtold
@subheading Syntax

@example
#include <stdlib.h>

long double _strtold(const char *s, char **endp);
@end example

@subheading Description

This function converts as many characters of @var{s} that look like a
floating point number into that number.  The floating point number may
also take the form of a hex floating point number (case-insensitively)
like this [+|-]0xH.HHHp[+|-]DDD.  It also recognises (case-insensitively)
``Inf'', ``Infinity'', ``NaN'', ``NaN(@var{optional decimal-number})'',
``NaN(@var{optional octal-number})'' and ``NaN(@var{optional hex-number})''.
If @var{endp} is not a null pointer, a pointer to the first unconverted
character will be stored in the location pointed to by @var{endp}.  

There is also a standardised version of this function:
@code{strtold} (@pxref{strtold}).

@subheading Return Value

The value represented by @var{s}. 

If @var{s} is ``Inf'' or ``Infinity'', with any variations of case and
optionally prefixed with ``+'' or ``-'', the return value is
@code{INFINITY} (if no prefix or a ``+'' prefix) or @code{-INFINITY}
(if the prefix is ``-'').  

If @var{s} is ``NaN'' or ``NaN()'', with any variations of case and
optionally prefixed with ``+'' or ``-'', the return value is
@code{(long double)NAN}.  If the prefix is ``-'' the sign bit in the
NaN will be set to 1.  

If @var{s} is ``NaN(@var{decimal-number})'', ``NaN(@var{octal-number})''
or ``NaN(@var{hex-number})'', with any variations of case
and optionally prefixed with ``+'' or ``-'', the return value is a NaN
with the mantissa bits set to the lower 63 bits
of @var{decimal-number}, @var{octal-number} or @var{hex-number}
and the most significant bit to 1 (the mantissa for long 
doubles consists of 64 bits where the most significant bit is the
integer bit which must be set for NaNs).  Use at most 16 hexadecimal
digits in @var{hex-number} or the internal conversion will overflow,
which results in a mantissa with all bits set.  If the bit pattern
given is 0 (which won't work as a representation of a NaN) @code{(long
double)NAN} will be returned.  If the prefix is ``-'' the sign bit in
the NaN will be set to 1.  Testing shows that SNaNs might be converted
into QNaNs (the second most significant bit will be set in the
mantissa).  

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char buf[] = "123ret";
char buf2[] = "0x123ret";
char buf3[] = "NAN(123)";
char buf4[] = "NAN(0x123)";
char buf5[] = "0x1234567.89ABCDefP+1234";
char *bp;
long double x, x2, x3, x4;

x = _strtold(buf, &bp);
x2 = _strtold(buf2, &bp);
x3 = _strtold(buf3, &bp);
x4 = _strtold(buf4, &bp);
x5 = _strtold(buf5, &bp);
@end example

@c -----------------------------------------------------------------------------
@node strtoll, strtoul, _strtold, Alphabetical List
@unnumberedsec strtoll
@c From file ./ansi/stdlib/strtoll.txh
@findex strtoll
@subheading Syntax

@example
#include <stdlib.h>

long long int strtoll(const char *s, char **endp, int base);
@end example

@subheading Description

This function converts as much of @var{s} as looks like an appropriate
number into the value of that number, and sets @var{*endp} to point to
the first unused character. 

The @var{base} argument indicates what base the digits (or letters)
should be treated as.  If @var{base} is zero, the base is determined by
looking for @code{0x}, @code{0X}, or @code{0} as the first part of the
string, and sets the base used to 16, 16, or 8 if it finds one.  The
default base is 10 if none of those prefixes are found.

@subheading Return Value

The value.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable


@subheading Example

@example
printf("Enter a number: "); fflush(stdout);
gets(buf);
char *bp;
printf("The value is %lld\n", strtoll(buf, &bp, 0));
@end example
@c -----------------------------------------------------------------------------
@node strtoul, strtoull, strtoll, Alphabetical List
@unnumberedsec strtoul
@c From file ./ansi/stdlib/strtoul.txh
@findex strtoul
@subheading Syntax

@example
#include <stdlib.h>

unsigned long strtoul(const char *s, char **endp, int base);
@end example

@subheading Description

This is just like @code{strtol} (@pxref{strtol}) except that the result
is unsigned. 

@subheading Return Value

The value.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
printf("Enter a number: "); fflush(stdout);
gets(buf);
char *bp;
printf("The value is %u\n", strtoul(buf, &bp, 0));
@end example

@c -----------------------------------------------------------------------------
@node strtoull, strtoumax, strtoul, Alphabetical List
@unnumberedsec strtoull
@c From file ./ansi/stdlib/strtoull.txh
@findex strtoull
@subheading Syntax

@example
#include <stdlib.h>

unsigned long long int strtoull(const char *s, char **endp, int base);
@end example

@subheading Description

This is just like @code{strtoll} (@pxref{strtoll}) except that the result
is unsigned. 

@subheading Return Value

The value.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable


@subheading Example

@example
printf("Enter a number: "); fflush(stdout);
gets(buf);
char *bp;
printf("The value is %llu\n", strtoull(buf, &bp, 0));
@end example
@c -----------------------------------------------------------------------------
@node strtoumax, strupr, strtoull, Alphabetical List
@unnumberedsec strtoumax
@c From file ./c99/inttypes/strumax.txh
@findex strtoumax
@subheading Syntax

@example
#include <inttypes.h>

uintmax_t strtoumax (const char *s, char **endp, int base);
@end example

@subheading Description

This is just like @code{strtoimax} (@pxref{strtoimax}) except that
the result is unsigned.

@subheading Return Value

The value.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C99; not C89
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable


@subheading Example

@example
printf("Enter a number: "); fflush(stdout);
gets(buf);
char *bp;
printf("The value is %" PRIuMAX "\n", strtoumax(buf, &bp, 0));
@end example
@c -----------------------------------------------------------------------------
@node strupr, strxfrm, strtoumax, Alphabetical List
@unnumberedsec strupr
@c From file ./compat/string/strupr.txh
@findex strupr
@subheading Syntax

@example
#include <string.h>

char *strupr(char *string);
@end example

@subheading Description

This function converts all lower case characters in @var{string} to
upper case. 

@subheading Return Value

@var{string}

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char buf[] = "Foo!";
strupr(buf);
@end example

@c -----------------------------------------------------------------------------
@node strxfrm, swab, strupr, Alphabetical List
@unnumberedsec strxfrm
@c From file ./ansi/string/strxfrm.txh
@findex strxfrm
@subheading Syntax

@example
#include <string.h>

size_t strxfrm(char *s1, const char *s2, size_t max);
@end example

@subheading Description

This copies characters from @var{s2} to @var{s1}, which must be able to
hold @var{max} characters.  Each character is transformed according to
the locale such that @code{strcmp(s1b, s2b)} is just like
@code{strcoll(s1, s2)} where @code{s1b} and @code{s2b} are the
transforms of @code{s1} and @code{s2}. 

@subheading Return Value

The actual number of bytes required to transform @var{s2}, including the
@code{NULL}. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node swab, symlink, strxfrm, Alphabetical List
@unnumberedsec swab
@c From file ./compat/stdlib/swab.txh
@findex swab
@subheading Syntax

@example
#include <stdlib.h>

void swab(const void *from, void *to, int nbytes);
@end example

@subheading Description

This function copies @var{nbytes} bytes from the address pointed to by
@var{from} to the address pointed by @var{to}, exchanging adjacent even
and odd bytes.  It is useful for carrying binary data between
little-endian and big-endian machines.  The argument @var{nbytes} should
be even, and the buffers @var{from} and @var{to} should not overlap.

@subheading Return Value
  
None.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node symlink, syms_init, swab, Alphabetical List
@unnumberedsec symlink
@c From file ./compat/unistd/symlink.txh
@findex symlink
@subheading Syntax

@example
#include <unistd.h>

int symlink(const char *exists, const char *new);
@end example

@subheading Description
DOS does not support symbolic links.  However, DJGPP emulates them---this 
function creates a file with special size and format, so other DJGPP 
library functions transparently work with file which is pointed to
by the symlink.  Of course, it does not work outside DJGPP programs.  
Those library functions which are simple wrappers about DOS calls do not
use symlinks neither.

@subheading Return Value

Zero in case of success, -1 in case of failure (and @code{errno} set to
the appropriate error code).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
symlink ("c:/djgpp/bin/grep", "c:/djgpp/bin/fgrep");
@end example

@c -----------------------------------------------------------------------------
@node syms_init, syms_line2val, symlink, Alphabetical List
@unnumberedsec syms_init
@c From file ./debug.txh
@findex syms_init

@subheading Syntax

@example
#include <debug/syms.h>

void syms_init (char *file);
@end example

@subheading Description

This function reads debugging symbols from the named @var{file}, which
should be an executable program (either a @file{.exe} file or a raw COFF
image created by @file{ld.exe}, the linker).  It then processes the
symbols: classifies them by type, sorts them by name and value, and
stores them in internal data structures used by other symbol-related
functions, such as @code{syms_val2name}, @code{syms_val2line}, etc.

You @strong{must} call @code{syms_init} before calling the other
@code{syms_*} functions.

Currently, @code{syms_init} only supports COFF and AOUT debugging
format, so programs compiled with @samp{-gstabs} cannot be processed by
it.

@subheading Return Value

None.

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  syms_init("c:/foo/bar/baz.exe");
@end example


@c -----------------------------------------------------------------------------
@node syms_line2val, syms_listwild, syms_init, Alphabetical List
@unnumberedsec syms_line2val
@c From file ./debug.txh
@findex syms_line2val

@subheading Syntax

@example
#include <debug/syms.h>

unsigned long syms_line2val (char *filename, int lnum);
@end example

@subheading Description

This function returns the address of the first instruction produced from
the line @var{lnum} of the source file @var{filename} that was linked
into a program whose symbols were read by a previous call to
@code{syms_init}.

COFF debugging format does not support pathnames, so @var{filename}
should not include leading directories, just the basename.

You must call @code{syms_init} (@pxref{syms_init}) before calling any of
the other @code{syms_*} functions for the first time.

@subheading Return Value

The address of the first instruction produced from the line, or zero if
@var{filename} is not found in the symbol table or if no executable code
was generated for line @var{lnum} in @var{filename}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
 syms_init ("foo.exe");
 printf ("Line 3 of foo.c is at address %lx\n",
          syms_line2val("foo.c", 3));
@end example
@c -----------------------------------------------------------------------------
@node syms_listwild, syms_module, syms_line2val, Alphabetical List
@unnumberedsec syms_listwild
@c From file ./debug.txh
@findex syms_listwild

@subheading Syntax

@example
#include <debug/syms.h>

void syms_listwild (char *pattern,
                    void (*handler) (unsigned long addr, char type_c,
                                     char *name, char *file, int lnum));
@end example

@subheading Description

This function walks through all the symbols that were read by a previous
call to @code{syms_init} (@pxref{syms_init}).  For each symbol whose
name matches @var{pattern}, it invokes the user-defined function
@var{handler}, passing it information about that symbol:

@table @code
@item address
the address of the symbol.

@item type_c
a letter that specifies the type of the symbol, as follows:

@table @samp
@item T
@itemx t
``text'', or code: usually a function.

@item D
@itemx d
data: an initialized variable.

@item B
@itemx b
``bss'': an uninitialized variable.

@item F
@item f
a function (in @code{a.out} file only).

@item V
@itemx v
a set element or pointer (in @code{a.out} file only).

@item I
@itemx i
an indirect symbol (in @code{a.out} file only).

@item U
@itemx u
an undefined (a.k.a.@: unresolved) symbol.

@item A
@itemx a
an absolute symbol.
@end table

@item name
the name of the symbol.

@item file
the source file name where the symbol is defined.

@item lnum
the line number on which the symbol is defined in the source file.
@end table

Since variables and functions defined in C get prepended with an
underscore @samp{_}, begin @var{pattern} with @samp{_} if you want it to
match C symbols.

You must call @code{syms_init} (@pxref{syms_init}) before calling any of
the other @code{syms_*} functions for the first time.

@subheading Return Value

None.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  void print_sym (unsigned long addr, char type_c,
                  char *name, char *file, int lnum)
  @{
    printf (file ? "%s: %lx %c %s:%d\n" : "%s: %lx %c\n",
            name, addr, type_c,
            file ? file : "", lnum );
  @}

  int main (void)
  @{
    syms_init ("foo.exe");
    /* List all the symbols which begin with "___djgpp".  */
    syms_listwild ("___djgpp*", print_sym);
    return 0;
  @}
@end example


@c -----------------------------------------------------------------------------
@node syms_module, syms_name2val, syms_listwild, Alphabetical List
@unnumberedsec syms_module
@c From file ./debug.txh
@findex syms_module

@subheading Syntax

@example
#include <debug/syms.h>

char *syms_module (int nfile);
@end example

@subheading Description

This function returns the name of the source file (a.k.a.@: module)
whose ordinal number in the symbol table is @var{nfile}.

You must call @code{syms_init} (@pxref{syms_init}) before calling any of
the other @code{syms_*} functions for the first time.

@subheading Return Value

The name of the source file, or a @code{NULL} pointer if @var{nfile} is
negative or larger than the total number of modules linked into the
program whose symbols were read by @code{syms_init}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable



@c -----------------------------------------------------------------------------
@node syms_name2val, syms_val2line, syms_module, Alphabetical List
@unnumberedsec syms_name2val
@c From file ./debug.txh
@findex syms_name2val

@subheading Syntax

@example
#include <debug/syms.h>
extern int undefined_symbol;
extern int syms_printwhy;

unsigned long syms_name2val (const char *string);
@end example

@subheading Description

This function returns the address of a symbol specified by @var{string}.
@var{string} may be one of the following:

@itemize @bullet
@item
A number, with or without a sign, in which case the number specifies the
address or an offset from an address.

@item
A file name and a line number: @code{@var{file}#[@var{line}]}, where
@var{file} is the name of one of the source files linked into the
program whose symbols were read by @code{syms_init}, and @var{line} is a
line number in that @var{file}.  If @var{line} is omitted, it defaults
to zero.

Note that the COFF format supported by DJGPP only stores the basename of
the source files, so do not specify @var{file} with leading directories.

@item
A symbol name as a string.  The name can be specified either with or
without the leading underscore @samp{_}.

@item
A register name @code{%@var{reg}}.  @var{reg} specifies the value of one
of the debuggee's registers saved in the external variable @code{a_tss}
(@pxref{run_child}).

@item
Any sensible combination of the above elements, see the example below.
@end itemize

@code{syms_name2val} looks up the specified file, line, and symbol in
the symbol table prepared by @code{syms_init}, finds their addresses,
adds the offset, if any, and returns the result.

If the specified file, line, or symbol cannot be found,
@code{syms_name2val} returns zero and sets the global variable
@code{undefined_symbol} to a non-zero value.  If the global variable
@code{syms_printwhy} is non-zero, an error message is printed
telling which part of the argument @var{string} was invalid.

You must call @code{syms_init} (@pxref{syms_init}) before calling any of
the other @code{syms_*} functions for the first time.

@subheading Return Value

The address specified by @var{string}, or zero, if none found.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
 unsigned long addr1, addr2, addr3;

 syms_init ("foo.exe");
 addr1 = syms_name2val ("foo.c#256+12");
 addr2 = syms_name2val ("_main");
 addr3 = syms_name2val ("struct_a_var+%eax+4");
@end example


@c -----------------------------------------------------------------------------
@node syms_val2line, syms_val2name, syms_name2val, Alphabetical List
@unnumberedsec syms_val2line
@c From file ./debug.txh
@findex syms_val2line

@subheading Syntax

@example
#include <debug/syms.h>

char *syms_val2line (unsigned long addr, int *line, int exact);
@end example

@subheading Description

This function takes an address @var{addr} and returns the source file
name which correspond to that address.  The line number in that source
file is stored in the variable pointed by @var{line}.  If @var{exact} is
non-zero, the function succeeds only if @var{addr} is the first address
which corresponds to some source line.

You must call @code{syms_init} (@pxref{syms_init}) before calling any of
the other @code{syms_*} functions for the first time.

@subheading Return Value

The name of the source file which corresponds to @var{addr}, or
@code{NULL} if none was found.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  int lineno;
  char *file_name;
  syms_init ("foo.exe");
  file_name = syms_val2line (0x1c12, &lineno);
  printf ("The address %x is on %s, line %d\n",
          0x1c12, file_name, line);
@end example


@c -----------------------------------------------------------------------------
@node syms_val2name, sync, syms_val2line, Alphabetical List
@unnumberedsec syms_val2name
@c From file ./debug.txh
@findex syms_val2name

@subheading Syntax

@example
#include <debug/syms.h>

char *syms_val2name (unsigned long addr, unsigned long *offset);
@end example

@subheading Description

This function takes an address @var{addr} and returns the name of the
closest symbol whose address is less that @var{addr}.  If @var{offset}
is not a @code{NULL} pointer, the offset of @var{addr} from the symbol's
address is stored in the variable pointed to by @var{offset}.

You must call @code{syms_init} (@pxref{syms_init}) before calling any of
the other @code{syms_*} functions for the first time.

This function is meant to be used to convert numerical addresses into
function names and offsets into their code, like what @code{symify} does
with the call frame traceback.

The function ignores several dummy symbols, like @samp{_end} and
@samp{_etext}.

@subheading Return Value

The name of the found symbol, or the printed hexadecimal representation
of @var{addr}, if no symbol was found near @var{addr}.  The return value
is a pointer to a static buffer, so don't overwrite it and don't pass it
to @code{free}!

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  unsigned long offs;
  char *symbol_name;
  syms_init ("foo.exe");
  symbol_name = syms_val2name (0x1c12, &offs);
  printf ("The address %x is at %s%+ld\n", 0x1c12, symbol_name, offs);
@end example


@c -----------------------------------------------------------------------------
@node sync, sys_errlist, syms_val2name, Alphabetical List
@unnumberedsec sync
@c From file ./compat/unistd/sync.txh
@findex sync
@subheading Syntax

@example
#include <unistd.h>

int sync(void);
@end example

@subheading Description

Intended to assist porting Unix programs.  Under Unix, @code{sync}
flushes all caches of previously written data.  In this implementation,
@code{sync} calls @code{fsync} on every open file.  @xref{fsync}.  It
also calls @code{_flush_disk_cache} (@pxref{_flush_disk_cache}) to try
to force cached data to the disk.

@subheading Return Value

Always returns 0.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
sync();
@end example

@c -----------------------------------------------------------------------------
@node sys_errlist, sys_nerr, sync, Alphabetical List
@unnumberedsec sys_errlist
@c From file ./ansi/string/syserrls.txh
@vindex sys_errlist
@subheading Syntax

@example
#include <errno.h>

extern char *sys_errlist[];
@end example

@subheading Description

This array contains error messages, indexed by @code{errno}, that
describe the errors. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
printf("Error: %s\n", sys_errlist[errno]);
@end example

@c -----------------------------------------------------------------------------
@node sys_nerr, sysconf, sys_errlist, Alphabetical List
@unnumberedsec sys_nerr
@c From file ./ansi/string/syserrls.txh
@vindex sys_nerr
@subheading Syntax

@example
#include <errno.h>

extern int sys_nerr;
@end example

@subheading Description

This variable gives the number of error messages in @code{sys_errlist}
(@pxref{sys_errlist}). 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
if (errno < sys_nerr)
  printf("Error: %s\n", sys_errlist[errno]);
@end example

@c -----------------------------------------------------------------------------
@node sysconf, _sysmalloc, sys_nerr, Alphabetical List
@unnumberedsec sysconf
@c From file ./posix/unistd/sysconf.txh
@findex sysconf
@subheading Syntax

@example
#include <unistd.h>

long sysconf(int which);
@end example

@subheading Description

This function returns various system configuration values, based on
@var{which}:

@example
  case _SC_ARG_MAX:	return _go32_info_block.size_of_transfer_buffer;
  case _SC_CHILD_MAX:	return CHILD_MAX;
  case _SC_CLK_TCK:	return CLOCKS_PER_SEC;
  case _SC_NGROUPS_MAX:	return NGROUPS_MAX;
  case _SC_OPEN_MAX:	return 255;
  case _SC_JOB_CONTROL:	return -1;
  case _SC_SAVED_IDS:	return -1;
  case _SC_STREAM_MAX:	return _POSIX_STREAM_MAX;
  case _SC_TZNAME_MAX:	return TZNAME_MAX;
  case _SC_VERSION:	return _POSIX_VERSION;
@end example

@subheading Return Value

The value.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node _sysmalloc, system, sysconf, Alphabetical List
@unnumberedsec _sysmalloc
@c From file ./ansi/stdlib/nmalloc.txh
@subheading Syntax

@example
#include <stdlib.h>
#include <malldbg.h>  /* on non-DJGPP systems */
#include <sysquery.h> /* alternative on non-DJGPP systems */

struct _sysquery _sysmalloc(void);
@end example

@subheading Description

This function exports the internal structure of the malloc arena
and thus allows construction of such packages as malldbg.  It 
avoids accidental exposure of system critical values, and also
permits such values to be changed and reflected in external
packages.

@subheading Return Value

A @code{struct _sysquery}, described as follows:

@example
struct _sysquery @{
  unsigned char data, gdlo, sz, prvf, nxtf, nxt, prv, ohead;
  void         *nilp;
  void         *anchors;
  set_m_hook    hookset;
@};
@end example

Any unsigned char field set to 255 signifies the value is
meaningless.  The @code{ohead} value is not useful in the
present implementation.  The remaining values are small offsets
from the internal pointers to the appropriate fields.  In
particular @code{data} is the offset between the internal
pointer and the user pointers.  @code{nxt} and @code{prv} link
all allocated memory blocks, while @code{nxtf} and @code{prvf}
are used only to link free blocks. @code{sz} is the internal
size of the block, not the user size, and is normally rounded
upward.  Thus the @code{nxt} field is redundant to the @code{sz}
field (except when no @code{nxt} exists) and is used in validity
checking. A @code{NULL} value in @code{nxtf} field signifies
that the block is not free. The special value @code{nilp} is
used in @code{nxtf} and @code{prvf} as a @code{NULL} value
distinguishable from @code{NULL}.

@code{anchors} points to a @code{NULL} terminated list of sets
of chains of memory blocks.  These were allocated by @code{sbrk}
and were not contiguous to any previous allocations.

@code{hookset} is a pointer to a function that can set malloc
hooks, as described in @code{mallsethook}.  It is only available
through this link.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


This function is specific to DJGPP.

@subheading Example

@example
struct _sysquery sysinfo = _sysmalloc();
@end example

@c -----------------------------------------------------------------------------
@node system, tan, _sysmalloc, Alphabetical List
@unnumberedsec system
@c From file ./ansi/stdlib/system.txh
@findex system
@vindex SHELL@r{ environment variable, and }system
@vindex COMSPEC@r{ environment variable, and }system
@vindex CMDLINE@r{ environment variable, and }system
@vindex DJSYSFLAGS@r{ environment variable, and the behaviour of }system
@subheading Syntax

@example
#include <stdlib.h>

int system(const char *cmd);
@end example

@subheading Description

This function runs the command or program specified by @var{cmd}.  If
@var{cmd} is a null pointer, @code{system} returns non-zero only if a
shell is available.  If @var{cmd} is an empty string, the command
processor pointed to by @samp{SHELL} or @samp{COMSPEC} variables in the
environment will be invoked interactively; type @kbd{exit @key{RET}} to
return to the program which called @code{system}.  (Note that some other
DOS compilers treat a null pointer like an empty command line, contrary
to ANSI C requirements.)

When calling programs compiled by DJGPP this function will not use
@file{COMMAND.COM} and so will not be subject to its 126 character limit
on command lines.

When the calling program runs on Windows 9X or Windows 2000 and calls
the system shell to run the child program, or if the child program is a
native Windows program (in @code{PE-COFF} format), or when the system
shell is @file{4DOS} or @file{NDOS}, command lines longer than 126
characters are passed via the environment variable @code{CMDLINE}.

Command lines and pipes (i.e., the use of @samp{<}, @samp{>}, @samp{>>},
and @samp{|}) will be simulated internally in this function; this means
that you can have both long command lines and redirection/pipes when
running DJGPP programs with this function.

By default, @file{COMMAND.COM} will only be invoked to run commands
internal to it, or to run batch files (but this can be changed, see
below).  In these cases, the returned error code will always be zero,
since @file{COMMAND.COM} always exits with code 0.

Certain commands internal to @file{COMMAND.COM} that don't make sense or
cause no effect in the context of @code{system} are ignored by this
function.  These are @code{REM}, @code{EXIT}, @code{GOTO}, @code{SHIFT};
@code{SET}, @code{PATH} and @code{PROMPT} are ignored only if called
with an argument.  You can disable this feature if you need, see below.

Some commands are emulated internally by @code{system}, because the
emulation is better than the original.  Currently, the only emulated
command is @samp{CD} or @samp{CHDIR}: the emulation knows about forward
slashes and also switches the current drive.  This emulation can also be
switched off, as explained below.

When @code{system} is presented with an internal shell command, it
checks the environment variables @samp{SHELL} and @samp{COMSPEC} (in
that order) and invokes the program that they point to.  If the shell
thus found is one of the DOS shells (@file{COMMAND.COM}, @file{4DOS} or
@file{NDOS}), they are called with the @samp{/c} switch prepended to the
command line.  Otherwise, @code{system} assumes that the shell is a
Unix-style shell and passes it the entire command line via a temporary
file, invoking the shell with a single argument which is the name of
that file.

Shell scripts and batch files are invoked by calling either the program
whose name appears on the first line (like in @w{@samp{#! /bin/sh}}), or
the default shell if none is specified by the script.  If the name of
the shell specified by the script is a Unix-style pathname, without a
drive letter and with no extension, @code{system} will additionally
search for it on the @samp{PATH}.  This allows to invoke Unix shell
scripts unmodified, if you have a ported shell installed on your
system.

You can customize the behavior of @code{system} using a bit-mapped
variable @code{__system_flags}, defined on @file{<stdlib.h>}.  The
following bits are currently defined:

@table @code
@item __system_redirect
When set (the default), specifies that @code{system} can use its
internal redirection and pipe code.  If reset, any command line that
includes an unquoted redirection symbol will be passed to the shell.

@item __system_call_cmdproc
When set, @code{system} will always call the shell to execute the
command line.  If reset (the default), the shell will only be called
when needed, as described above.

You should @emph{always} set this bit if you use a real, Unix-style
shell (also, set @code{__system_use_shell}, described below, and the
@samp{SHELL} environment variable).

@item __system_use_shell
When set (the default), the @samp{SHELL} environment variable will take
precedence upon @samp{COMSPEC}; this allows you to specify a special
shell for @code{system} that doesn't affect the rest of DOS.  If reset,
only @samp{COMSPEC} is used to find the name of the command processor.

@item __system_allow_multiple_cmds
When set, you can put multiple commands together separated by the
@samp{;} character.  If reset (the default), the command line passed to
@code{system} is executed as a single command and @samp{;} has no
special meaning.

@item __system_allow_long_cmds
When set (the default), @code{system} will handle command lines longer
than the DOS 126-character limit; this might crash your program in some
cases, as the low-level functions that invoke the child program will
only pass them the first 126 characters.  When reset, @code{system} will
detect early that the command line is longer than 126 characters and
refuse to run it, but you will not be able to call DJGPP programs with
long command lines.

@item __system_emulate_command
If reset (the default), @code{system} will pass the entire command line
to the shell if its name is one of the following: @file{sh.exe},
@file{sh16.exe}, @file{sh32.exe}, @file{bash.exe}, @file{tcsh.exe}.
When set, @code{system} will attempt to emulate redirection and pipes
internally, even if @samp{COMSPEC} or @samp{SHELL} point to a Unix-style
shell.

@item __system_handle_null_commands
When set (the default), commands internal to @file{COMMAND.COM} and
compatible shells which have no effect in the context of @code{system},
are ignored (the list of these commands was given above).  If reset,
these commands are processed as all others, which means
@file{COMMAND.COM} will be called to execute them.

Note that this bit shouldn't be used with a Unix-style shell, because it
does the wrong thing then.  With Unix-style shells, you are supposed to
set the @code{__system_call_cmdproc} bit which will always call the
shell.

@item __system_ignore_chdir
If set, the @samp{CD} and @samp{CHDIR} commands are ignored.  When reset
(the default), the processing of these commands depends on the
@code{__system_emulate_chdir} bit, see below.

This bit is for compatibility with Unix, where a single @samp{cd dir}
command has no effect, because the current working directory there is
not a global notion (as on MSDOS).  Don't set this bit if you use
multiple commands (see @code{__system_allow_multiple_cmds} above).

@item __system_emulate_chdir
When set, the @samp{CD} and @samp{CHDIR} commands are emulated
internally: they change the drive when the argument specifies a drive
letter, and they support both forward slashes and backslashes in
pathnames.  When @samp{CD} is called without an argument, it prints the
current working directory with forward slashes and down-cases DOS 8+3
names.  If this bit is reset (the default), @samp{CD} and @samp{CHDIR}
are passed to the shell.
@end table

The behavior of @code{system} can be customized at run time by defining
the variable @samp{DJSYSFLAGS} in the environment.  The value of that
variable should be the numerical value of @code{__system_flags} that
you'd like to set; it will override the value of @code{__system_flags}
specified when the program was compiled.

@subheading Return Value

If @var{cmd} is a null pointer, @code{system} returns non-zero if a
shell is available.  The actual test for the existence of an executable
file pointed to by @samp{SHELL} or @samp{COMSPEC} is only performed if
the shell is to be invoked to process the entire command line; if most
of the work is to be done by @code{system} itself, passing a null
pointer always yields a non-zero return value, since the internal
emulation is always ``available''.

Otherwise, the return value is the exit status of the child process in
its lower 8 bits; bits 8-17 of the return value will hold @code{SIGINT}
or @code{SIGABRT} if the child process was aborted by @kbd{Ctrl-C} or
Critical Device Error, respectively; otherwise they will be zero@footnote{
Many DOS programs catch @kbd{Ctrl-C} keystrokes and Critical Errors, and
handle them in customized ways.  If this handling prevents DOS from
realizing that the program was aborted due to these reasons, bits 8-17
of the value returned by @code{system} will most probably be zero.
Don't count on these bits to hold the signal number!}.  If the
child couldn't be run, @code{system} will return -1 and set @code{errno}
to an appropriate value.  Note that if @file{COMMAND.COM} was used to
run the child, it will always return a 0 status, even if the command
didn't run successfully.  However, @code{system} only calls
@file{COMMAND.COM} when it needs to run commands internal to it.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
system("cc1plus.exe @@cc123456.gp");
@end example


@c -----------------------------------------------------------------------------
@node tan, tanh, system, Alphabetical List
@unnumberedsec tan
@c From file ./ansi/math/tan.txh
@findex tan
@subheading Syntax

@example
#include <math.h>

double tan(double x);
@end example

@subheading Description

This function computes the tangent of @var{x} (which should be given in
radians).

@subheading Return Value

The tangent of @var{x}.  If the absolute value of @var{x} is finite but
greater than or equal to @math{2^63}, the return value is 0 (since for
arguments that large each bit of the mantissa is more than @code{Pi}).
If the value of @var{x} is infinite or @code{NaN}, the return value is
@code{NaN} and @code{errno} is set to @code{EDOM}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable

@c -----------------------------------------------------------------------------
@node tanh, tcdrain, tan, Alphabetical List
@unnumberedsec tanh
@c From file ./ansi/math/tanh.txh
@findex tanh
@subheading Syntax

@example
#include <math.h>

double tanh(double x);
@end example

@subheading Description

This function computes the hyperbolic tangent of @var{x}.

@subheading Return Value

The hyperbolic tangent of @var{x}.  If @var{x} is either a positive or a
negative infinity, the result is unity with the same sign as @var{x},
and @code{errno} is not changed.  If @var{x} is @code{NaN}, the return
value is @code{NaN} and @code{errno} is set to @code{EDOM}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node tcdrain, tcflow, tanh, Alphabetical List
@unnumberedsec tcdrain
@c From file ./posix/termios/tcdrain.txh
@findex tcdrain
@subheading Syntax

@example
#include <termios.h>

int tcdrain (int fd);
@end example

@subheading Description

This function waits until all the output is written to the file/device
referred to by the handle @var{fd}.  In this implementation, this
function does nothing except checking the validity of its arguments; it
is provided for compatibility only.  Note that the termios emulation
handles console only.

@subheading Return Value

Zero on success, nonzero on failure.



@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node tcflow, tcflush, tcdrain, Alphabetical List
@unnumberedsec tcflow
@c From file ./posix/termios/tcflow.txh
@findex tcflow
@subheading Syntax

@example
#include <termios.h>

int tcflow (int fd, int action);
@end example

@subheading Description

This function suspends transmission of data to, or reception of data
from, the device/file open on handle @var{fd}.  The @var{action}
argument can take one of these values:

@table @code
@item TCOOFF
the output is suspended
@item TCOON
the output is resumed
@item TCIOFF
the STOP character is transmitted
@item TCION
the START character is transmitted
@end table

The current START and STOP characters are stored in the @code{termios}
structure that is currently in effect.  @xref{Termios functions}, for
more details about that.

Note that the DJGPP termios emulation handles console only.

@subheading Return Value

Zero on success, nonzero on failure.



@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node tcflush, tcgetattr, tcflow, Alphabetical List
@unnumberedsec tcflush
@c From file ./posix/termios/tcflush.txh
@findex tcflush
@subheading Syntax

@example
#include <termios.h>

int tcflush (int fd, int which);
@end example

@subheading Description

This function clears the input and/or output queues on for the
device/file open on handle @var{fd}.  The @var{which} argument can take
these values:

@table @code
@item TCIFLUSH
the unprocessed characters in the input buffer are discarded
@item TCOFLUSH
no effect (provided for compatibility)
@item TCIOFLUSH
has the combined effect of @code{TCIFLUSH} and @code{TCOFLUSH}
@end table

Note that the termios emulation handles console only.

@subheading Return Value

Zero on success, nonzero on failure.



@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node tcgetattr, tcgetpgrp, tcflush, Alphabetical List
@unnumberedsec tcgetattr
@c From file ./posix/termios/tcgetatr.txh
@findex tcgetattr
@subheading Syntax

@example
#include <termios.h>

int tcgetattr (int fd, struct termios *termiosp);
@end example

@subheading Description

This function gets the parameters associated with the file/device
referred to by the handle @var{fd} and stores them in the termios
structure @var{termiosp}.  @xref{Termios functions}, for the full
description of @code{struct termios} and its members.

Note that the termios emulation handles console only.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
struct termios termiosbuf;
int rc = tcgetattr (0, &termiosbuf);
@end example


@c -----------------------------------------------------------------------------
@node tcgetpgrp, tcsendbreak, tcgetattr, Alphabetical List
@unnumberedsec tcgetpgrp
@c From file ./posix/termios/tcgetpgr.txh
@findex tcgetpgrp
@subheading Syntax

@example
#include <termios.h>

int tcgetpgrp (int fd);
@end example

@subheading Description

This function returns the value of the @dfn{process group ID} for the
foreground process associated with the terminal.  The file descriptor
@var{fd} must be connected to the terminal, otherwise the function will
fail.

@subheading Return Value

If @var{fd} is connected to the terminal, the function returns the
process group ID, which is currently identical to the value returned by
@code{getpgrp()} (@pxref{getpgrp}).  Otherwise, it returns -1 and sets
@code{errno} to @code{ENOTTY}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable



@c -----------------------------------------------------------------------------
@node tcsendbreak, tcsetattr, tcgetpgrp, Alphabetical List
@unnumberedsec tcsendbreak
@c From file ./posix/termios/tcsndbrk.txh
@findex tcsendbreak
@subheading Syntax

@example
#include <termios.h>

int tcsendbreak (int fd, int duration);
@end example

@subheading Description

This function generates a break condition for @code{@var{duration}*0.25}
seconds.  In the current implementation this function does nothing; it
is provided for compatibility only.  Note that the termios emulation
handles console only.

@subheading Return Value

Zero on success, nonzero on failure.



@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node tcsetattr, tcsetpgrp, tcsendbreak, Alphabetical List
@unnumberedsec tcsetattr
@c From file ./posix/termios/tcsetatr.txh
@findex tcsetattr
@subheading Syntax

@example
#include <termios.h>

int tcsetattr (int fd, int action, const struct termios *termiosp);
@end example

@subheading Description

This function sets termios structure for device open on the handle
@var{fd} from the structure @var{termiosp}.  Note that the termios
emulation handles console only.

The @var{action} argument can accept the following values:

@table @code
@item TCSANOW

@item TCSADRAIN

@item TCSAFLUSH
@end table

Currently, any of these values causes the values in @var{termiosp} to
take effect immediately.

@xref{Termios functions}, for the description of the @code{struct
termios} structure.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
tcsetattr (0, TCSANOW, &termiosbuf);
@end example


@c -----------------------------------------------------------------------------
@node tcsetpgrp, tell, tcsetattr, Alphabetical List
@unnumberedsec tcsetpgrp
@c From file ./posix/termios/tcgetpgr.txh
@findex tcsetpgrp
@subheading Syntax

@example
#include <termios.h>

int tcsetpgrp (int fd, pid_t pgroup_id);
@end example

@subheading Description

This function sets the foreground @dfn{process group ID} for the
terminal connected to file descriptor @var{fd}.  @var{fd} must be a
valid handle connected to a terminal device, and @var{pgroup_id} must be
the process group ID of the calling process, or the function will fail.

@subheading Return Value

If @var{fd} is a valid handle connected to a terminal and
@var{pgroup_id} is equal to what @code{getpgrp()} returns
(@pxref{getpgrp}), the function will do nothing and return zero.
Otherwise, -1 will be returned and @code{errno} will be set to a
suitable value.  In particular, if the @var{pgroup_id} argument is
different from what @code{getpgrp()} returns, @code{tcsetpgrp} sets
@code{errno} to @code{ENOSYS}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable

@c -----------------------------------------------------------------------------
@node tell, telldir, tcsetpgrp, Alphabetical List
@unnumberedsec tell
@c From file ./dos/io/tell.txh
@findex tell
@subheading Syntax

@example
#include <io.h>

off_t tell(int file);
@end example

@subheading Description

This function returns the location of the file pointer for @var{file}. 

@subheading Return Value

The file pointer, or -1 on error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
off_t q = tell(fd);
@end example

@c -----------------------------------------------------------------------------
@node telldir, tempnam, tell, Alphabetical List
@unnumberedsec telldir
@c From file ./posix/dirent/telldir.txh
@findex telldir
@subheading Syntax

@example
#include <dirent.h>

long telldir(DIR *dir);
@end example

@subheading Description

This function returns a value which indicates the position of the
pointer in the given directory.  This value is only useful as an
argument to @code{seekdir} (@pxref{seekdir}). 

@subheading Return Value

The directory pointer.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
DIR *dir;
long q = telldir(dir);
do_something();
seekdir(dir, q);
@end example

@c -----------------------------------------------------------------------------
@node tempnam, Termios functions, telldir, Alphabetical List
@unnumberedsec tempnam
@c From file ./compat/stdio/tempnam.txh
@findex tempnam
@vindex TMPDIR@r{ environment variable, and }tempnam
@vindex TEMP@r{ environment variable, and }tempnam
@vindex TMP@r{ environment variable, and }tempnam
@subheading Syntax

@example
#include <stdio.h>

char * tempnam(const char *tmpdir, const char *prefix);
@end example

@subheading Description

This function generates a file name which can be used for a temporary
file, and makes sure that no other file by that name exists.

The caller has control on the choice of the temporary file's directory,
and the initial letters of the file's basename.  If the argument
@var{tmpdir} points to the name of the directory in which the temporary
file will be created, @code{tempnam} will ensure that the generate name
is unique @strong{in that directory}.  If the argument @var{prefix}
points to a string, then that string will be used as the first few
characters of the file's basename.  Due to limitations of the DOS 8.3
file namespace, only up to two first characters in @var{prefix} will be
used.

If @var{tmpdir} is @code{NULL}, or empty, or points to a non-existent
directory, @code{tempnam} will use a default directory.  The default
directory is determined by testing, in sequence, the directories
defined by the values of environment variables @code{TMPDIR},
@code{TEMP} and @code{TMP}.  The first variable that is found to point
to an existing directory will be used.  If none of these variables
specify a valid directory, @code{tempnam} will use the static default
path prefix defined by @code{P_tmpdir} on @file{<stdio.h>}, or
@code{"c:/"}, in that order.

If @var{prefix} is @code{NULL} or empty, @code{tempnam} will supply its
own default prefix @code{"tm"}.

@code{tempnam} puts the generated name into space allocated by
@code{malloc}.  It is up to the caller to free that space when it is no
longer needed.

Note that @code{tempnam} does not actually create the file, nor does it
ensure in any way that the file will be automatically deleted when it's
no longer used.  It is the user's responsibility to do that.

@subheading Return Value

On success, @code{tempnam} returns a pointer to space (allocated with a
call to @code{malloc}) where the file name is constructed.  If
@code{malloc} failed to provide sufficient memory buffer, or if no valid
directory to hold the file was found, @code{tempnam} returns a
@code{NULL} pointer.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  #include <stdio.h>

    tempnam ("c:/tmp/", "foo");

@end example
@c -----------------------------------------------------------------------------
@node Termios functions, textattr, tempnam, Alphabetical List
@unnumberedsec Termios functions
@c From file ./posix/termios/tcsetatr.txh
@cindex termios
@tindex termios@r{ structure}

The @code{termios} functions allow to control terminals and asynchronous
communications ports.  The DJGPP implementation currently supports the
@code{termios} functionality for console devices only.  It does that by
reading the keyboard via the BIOS Int 16h and writes to the screen via
the direct output interrupt 29h.  This I/O redirection is performed by
the special hook internal to the library.

Many of the @code{termios} functions accept a @var{termiosp} argument
which is a pointer to a @code{struct termios} variable.  Here's the
description of this structure:

@example
 #define NCCS 12
 struct termios @{
   cc_t	        c_cc[NCCS];  /* control characters */
   tcflag_t     c_cflag;     /* control modes */
   tcflag_t     c_iflag;     /* input modes */
   tcflag_t     c_lflag;     /* local modes */
   tcflag_t     c_oflag;     /* output modes */
   speed_t      c_ispeed;    /* input baudrate */
   speed_t      c_ospeed;    /* output baudrate */
 @}
@end example

The array @code{c_cc[]} defines the special control characters.  the
following table lists the supported control functions the default
characters which invoke those functions, and the default values for MIN
and TIME parameters:

@multitable {Index} {VERASE} {Delete previous character} {Backspace}
@item Index @tab Name @tab Function @tab Default Value
@item 1 @tab VEOF @tab Signal End-Of-Input @tab Ctrl-D
@item 2 @tab VEOL @tab Signal End-Of-Line @tab [Disabled]
@item 3 @tab VERASE @tab Delete previous character @tab Backspace
@item 4 @tab VINTR @tab Generate SIGINT @tab Ctrl-C
@item 5 @tab VKILL @tab Erase current line @tab Ctrl-U
@item 6 @tab VMIN @tab The MIN value @tab 1
@item 7 @tab VQUIT @tab Generate SIGQUIT @tab Ctrl-\
@item 8 @tab VSTART @tab Resume output @tab Ctrl-Q
@item 9 @tab VSTOP @tab Suspend output @tab Ctrl-S
@item 10 @tab VSUSP @tab Suspend program @tab Ctrl-Z
@item 11 @tab VTIME @tab TIME value @tab 0
@end multitable

The special characters (like @code{VEOL}, @code{VKILL}, etc.) produce
their effect only under the @dfn{canonical input processing}, that is,
when the @code{ICANON} bit in the @code{c_lflag} member of @code{struct
termios} (see below) is set.  If @code{ICANON} is @strong{not} set, all
characters are processed as regular characters and returned to the
caller; only the @code{VMIN} and @code{VTIME} parameters are meaningful
in the @dfn{non-canonical processing} mode.

The @code{VEOL} character can be used to signal end of line (and thus
end of input in the canonical mode) in addition to the normal @kbd{RET}
key.  In the non-canonical mode, input ends as soon as at least
@code{VMIN} characters are received.

Note that the values of @code{VMIN} and @code{VTIME} are currently
ignored; @code{termios} functions always work as if @code{VMIN} were 1
and @code{VTIME} were zero.  Other parameters are supported (for console
devices only), except that VSTOP and VSTART characters are not inserted
to the input, but otherwise produce no effect.

The @code{c_cflag} member of @code{struct termios} describes the
hardware terminal control, as follows:

@multitable {Symbol} {If set, send two stop bits}
@item Symbol @tab Function
@item B0 @tab Hang up
@item B50 @tab 50 baud
@item B75 @tab 75 baud
@item B110 @tab 110 baud
@item B134 @tab 134.5 baud
@item B150 @tab 150 baud
@item B200 @tab 200 baud
@item B300 @tab 300 baud
@item B600 @tab 600 baud
@item B1200 @tab 1200 baud
@item B1800 @tab 1800 baud
@item B2400 @tab 2400 baud
@item B4800 @tab 4800 baud
@item B9600 @tab 9600 baud
@item B19200 @tab 19200 baud
@item B38400 @tab 38400 baud
@item CSIZE @tab Character size:
@item CS5 @tab 5-bit characters
@item CS6 @tab 6-bit characters
@item CS7 @tab 7-bit characters
@item CS8 @tab 8-bit characters
@item CSTOPB @tab If set, send two stop bits
@item CREAD @tab Enable reading
@item PARENB @tab Enable parity
@item PARODD @tab If set, use odd parity
@item HUPCL @tab Hang up on last close
@item CLOCAL @tab If set, line is local
@end multitable

Note that since the DOS terminal doesn't use asynchronous ports, the
above parameters are always ignored by the implementation.  The default
value of @code{c_cflag} is @code{(CS8|CREAD|CLOCAL)}.

The @code{c_lflag} member of @code{struct termios} defines the local
modes that control the terminal functions:

@multitable {Symbol} {Canonical input (erase and kill processing)}
@item Symbol @tab Function
@item ISIG @tab If set, enable signals SIGINT and SIGQUIT
@item ICANON @tab If set, enable canonical input processing
@item ECHO @tab If set, enable echoing
@item ECHOE @tab Erase character deletes
@item ECHOK @tab Output newline after the kill character
@item ECHONL @tab Echo the newline
@item NOFLSH @tab [Ignored]
@item TOSTOP @tab [Ignored]
@item ECHOCTL @tab Echo control characters as ^X
@item ECHOKE @tab Erase killed line
@item IEXTEN @tab [Ignored]
@end multitable

The default value of @code{c_lflag} is
@code{(ISIG|ICANON|ECHO|IEXTEN|ECHOE|ECHOKE|ECHOCTL)}.

The @code{c_iflag} member of @code{struct termios} describes the input
control:

@multitable {Symbol} {Map upper-case to lower-case on input}
@item Symbol @tab Function
@item IGNBRK @tab Ignore Ctrl-BREAK
@item BRKINT @tab Generate SIGINT on Ctrl-BREAK
@item IGNPAR @tab [Ignored]
@item PARMRK @tab [Ignored]
@item INPCK @tab [Ignored]
@item ISTRIP @tab Strip the 8th bit from input
@item INLCR @tab Map NL to CR on input
@item IGNCR @tab Ignore CR characters
@item ICRNL @tab Map CR to NL on input
@item IXON @tab [Ignored]
@item IXOFF @tab Enable start/stop input control
@item IMAXBEL @tab Ring the bell if input line too long
@end multitable

The default value of @code{c_iflag} is @code{(BRKINT|ICRNL|IMAXBEL)}.

The @code{c_oflag} member of @code{struct termios} specifies the output
handling:

@multitable {Symbol} {Map lower case to upper on output}
@item Symbol @tab Function
@item OPOST @tab If not set, output characters verbatim
@item ONLCR @tab Map newline to CR-LF pair on output
@item OCRNL @tab Map CR to NL on output
@item ONOEOT @tab Don't output EOT characters
@end multitable

Note that if the @code{OPOST} bit is not set, all the other flags are
ignored and the characters are output verbatim.  The default value of
@code{c_oflag} is @code{(OPOST|ONLCR|ONOEOT)}.

The @code{c_ispeed} and @code{c_ospeed} members specify, respectively,
the input and output baudrate of the terminal.  They are set by default
to 9600 baud, but the value is always ignored by this implementation,
since no asynchronous ports are used.

@c -----------------------------------------------------------------------------
@node textattr, textbackground, Termios functions, Alphabetical List
@unnumberedsec textattr
@c From file ./pc_hw/co80/conio.txh
@findex textattr
@subheading Syntax

@example
#include <conio.h>

void textattr(int _attr);
@end example

@subheading Description

Sets the attribute used for future writes to the screen:

@example
---- XXXX = foreground color
-XXX ---- = background color
X--- ---- = 1=blink 0=steady
@end example

The include file <conio.h> contains an enum COLORS that define the
various values that can be used for these bitfields; light colors can
only be used for the foreground.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
/* blinking white on blue */
textattr(BLINK | (BLUE << 4) | WHITE);
@end example

@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node textbackground, textcolor, textattr, Alphabetical List
@unnumberedsec textbackground
@c From file ./pc_hw/co80/conio.txh
@findex textbackground
@subheading Syntax

@example
#include <conio.h>

void textbackground(int _color);
@end example

@subheading Description

Sets just the background of the text attribute. @xref{textattr}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node textcolor, textmode, textbackground, Alphabetical List
@unnumberedsec textcolor
@c From file ./pc_hw/co80/conio.txh
@findex textcolor
@subheading Syntax

@example
#include <conio.h>

void textcolor(int _color);
@end example

@subheading Description

Sets just the foreground of the text attribute. @xref{textattr}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node textmode, time, textcolor, Alphabetical List
@unnumberedsec textmode
@c From file ./pc_hw/co80/conio.txh
@findex textmode
@subheading Syntax

@example
#include <conio.h>

void textmode(int _mode);
@end example

@subheading Description

Sets the text mode of the screen.  @var{_mode} is one of the
following:

@table @code

@item LASTMODE

The text mode which was in effect @emph{before} the last call to
@code{textmode()}.

@item BW40

40-column black and white (on a color screen)

@item C40

40-color color.

@item BW80

80-column black and white (on a color screen)

@item C80

80-column color

@item MONO

The monochrome monitor

@item C4350

80-column, 43- (on EGAs) or 50-row (on VGAs) color

@end table

@xref{_set_screen_lines}, for a more versatile method of setting
text screen dimensions.
@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node time, times, textmode, Alphabetical List
@unnumberedsec time
@c From file ./ansi/time/time.txh
@findex time
@subheading Syntax

@example
#include <time.h>

time_t time(time_t *t);
@end example

@subheading Description

If @var{t} is not @code{NULL}, the current time is stored in @code{*t}. 

@subheading Return Value

The current time is returned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
printf("Time is %d\n", time(0));
@end example

@c -----------------------------------------------------------------------------
@node times, tmpfile, time, Alphabetical List
@unnumberedsec times
@c From file ./posix/sys/times/times.txh
@findex times
@tindex tms@r{ structure}
@subheading Syntax

@example
#include <sys/times.h>

clock_t times(struct tms *buf);
@end example

@subheading Description

This function returns the number of clock ticks used by the current
process and all of its children until the moment of call.  The number
of tics per second is @code{CLOCKS_PER_SEC}, defined on time.h.

This is the structure in which @code{times} returns its info:

@example
struct  tms @{
  clock_t tms_cstime;
  clock_t tms_cutime;
  clock_t tms_stime;
  clock_t tms_utime;
@};
@end example

Currently, the elapsed time of the running program is returned in the
@code{tms_utime} field, and all other fields return as zero.

@subheading Return Value

The number of elapsed tics since the program started.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
printf("We used %d seconds of elapsed time\n",
       times(&buf)/CLOCKS_PER_SEC);
@end example

@c -----------------------------------------------------------------------------
@node tmpfile, tmpnam, times, Alphabetical List
@unnumberedsec tmpfile
@c From file ./ansi/stdio/tmpfile.txh
@findex tmpfile
@subheading Syntax

@example
#include <stdio.h>

FILE *tmpfile(void);
@end example

@subheading Description

This function opens a temporary file.  It will automatically be
removed if the file is closed or when the program exits.  The name of
the file is generated by the same algorithm as described under
tmpnam() (@pxref{tmpnam}).

@subheading Return Value

A newly opened file.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
FILE *tmp = tmpfile();
@end example

@c -----------------------------------------------------------------------------
@node tmpnam, toascii, tmpfile, Alphabetical List
@unnumberedsec tmpnam
@c From file ./ansi/stdio/tmpnam.txh
@findex tmpnam
@vindex TMPDIR@r{ environment variable, and }tmpnam
@vindex TEMP@r{ environment variable, and }tmpnam
@vindex TMP@r{ environment variable, and }tmpnam
@subheading Syntax

@example
#include <stdio.h>

char *tmpnam(char *s);
@end example

@subheading Description

This function generates a string that is a valid file name and that
is not the same as the name of an existing file.  A different string is
guaranteed to be produced each time it is called, up to @code{TMP_MAX}
times (@code{TMP_MAX} is defined on stdio.h).  If @code{tmpnam} is called
more than TMP_MAX times, the behavior is implementation-dependent (ours
just wraps around and tries to reuse the same file names from the
beginning).

This function examines the environment to determine the directory in which
the temporary file will be opened.  It looks for one of the variables
@code{"TMPDIR"}, @code{"TEMP"} and @code{"TMP"}, in that order.  The first
one which is found in the environment will be used on the assumption that
it points to a directory.  If neither of the above variables is defined,
@code{tmpnam} defaults to the "c:/" directory (which under MS-DOS might
mean that it fails to generate TMP_MAX unique names, because DOS root
directories cannot grow beyond certain limits).

@subheading Return Value

If @var{s} is a null pointer, @code{tmpnam} leaves its result in an
internal static buffer and returns a pointer to that buffer.  If @var{s}
is not a null pointer, it is assumed to point to an array of at least
@code{L_tmpnam} characters, and @code{tmpnam} writes its result in that
array and returns a pointer to it as its value.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
char buf[L_tmpnam];
char *s = tmpnam(buf);
@end example

@c -----------------------------------------------------------------------------
@node toascii, _tolower, tmpnam, Alphabetical List
@unnumberedsec toascii
@c From file ./ansi/ctype/toascii.txh
@findex toascii
@subheading Syntax

@example
#include <ctype.h>

int toascii(int c);
@end example

@subheading Description

This function strips the high bit of @var{c}, forcing it to be an
ASCII character.

@subheading Return Value

The ASCII character.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
for (i=0; buf[i]; i++)
  buf[i] = toascii(buf[i]);
@end example

@c -----------------------------------------------------------------------------
@node _tolower, tolower, toascii, Alphabetical List
@unnumberedsec _tolower
@c From file ./posix/ctype/_tolower.txh
@findex _tolower
@subheading Syntax

@example
#include <ctype.h>

int _tolower(int c);
@end example

@subheading Description

This function returns @var{c}, converting it to lower case.  For the reverse,
use @code{_toupper} (@pxref{_toupper}).

This function is like @code{tolower} (@pxref{tolower}), except that
the caller should ensure that @var{c} is upper case.

@subheading Return Value

The lower case letter.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable


@subheading Example

@example
for (i=0; buf[i]; i++)
  buf[i] = _tolower(buf[i]);
@end example
@c -----------------------------------------------------------------------------
@node tolower, _toupper, _tolower, Alphabetical List
@unnumberedsec tolower
@c From file ./ansi/ctype/tolower.txh
@findex tolower
@subheading Syntax

@example
#include <ctype.h>

int tolower(int c);
@end example

@subheading Description

This function returns @var{c}, converting it to lower case if it is
upper case.  @xref{toupper}.

@subheading Return Value

The lower case letter.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
for (i=0; buf[i]; i++)
  buf[i] = tolower(buf[i]);
@end example

@c -----------------------------------------------------------------------------
@node _toupper, toupper, tolower, Alphabetical List
@unnumberedsec _toupper
@c From file ./posix/ctype/_toupper.txh
@findex _toupper
@subheading Syntax

@example
#include <ctype.h>

int _toupper(int c);
@end example

@subheading Description

This function returns @var{c}, converting it to upper case.  For the reverse,
use @code{_tolower} (@pxref{_tolower}).

This function is like @code{toupper} (@pxref{toupper}), except that
the caller should ensure that @var{c} is lower case.

@subheading Return Value

The upper case letter.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable


@subheading Example

@example
for (i=0; buf[i]; i++)
  buf[i] = _toupper(buf[i]);
@end example
@c -----------------------------------------------------------------------------
@node toupper, _truename, _toupper, Alphabetical List
@unnumberedsec toupper
@c From file ./ansi/ctype/toupper.txh
@findex toupper
@subheading Syntax

@example
#include <ctype.h>

int toupper(int c);
@end example

@subheading Description

This function returns @var{c}, converting it to upper case if it is
lower case. @xref{tolower}.

@subheading Return Value

The upper case letter.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
for (i=0; buf[i]; i++)
  buf[i] = toupper(buf[i]);
@end example

@c -----------------------------------------------------------------------------
@node _truename, _truename_sfn, toupper, Alphabetical List
@unnumberedsec _truename
@c From file ./dos/dos/truename.txh
@findex _truename
@subheading Syntax

@example
#include <sys/stat.h>

char * _truename(const char *path, char *true_path);
@end example

@subheading Description

Given a @var{path} of a file, returns in @var{true_path} its canonicalized
pathname, with all letters uppercased, default drive and directory made
explicit, forward slashes converted to backslashes, asterisks converted to
appropriate number of of question marks, file and directory names
truncated to 8.3 if necessary, "." and ".." resolved, extra slashes (but
the last, if present) removed, SUBSTed, JOINed and ASSIGNed drives
resolved.  Character devices return as "X:/DEVNAME" (note the forward
slash!), where X is the CURRENT drive and DEVNAME is the device name (e.g.
CON).  This is exactly what DOS TRUENAME command does.  See Ralph Brown's
Interrupt List for more details.

The named @var{path} doesn't have to exist, but the drive, if given as
part of it, should be a legal DOS drive, as this function hits the disk.

The function will fail if given a @var{path} which (1) is an empty string;
or (2) contains only the drive letter (e.g. "c:"); or (3) has leading
whitespace.  It will also fail if it couldn't allocate memory required for
its communication with DOS or for @var{true_path} (see below).

@code{_truename} may not return what you expect for files that don't exist.
For instance, if the current directory was entered using a short
filename (@samp{c:\thisis~1} instead of @samp{c:\thisisalongname}, say),
then the truename of an existing file will be a long filename,
but the truename of an non-existing file will be a short filename.
This can cause problems when comparing filenames.  Use
@code{_truename_sfn} (@pxref{_truename_sfn}) instead in this case.

Upon success, the function will place the result in @var{true_path},
if that's non-NULL; the buffer should be large enough to contain the
largest possible pathname (PATH_MAX characters).  If @var{true_path}
is a NULL pointer, the space to hold the result will be allocated by
calling @code{malloc} (@pxref{malloc}); it is up to the caller to release
the buffer by calling @code{free} (@pxref{free}).

@subheading Return Value

The function returns the pointer to the result.  In case of any failure,
a NULL pointer is returned, and @code{errno} is set.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  fprintf(stderr, 
          "True name of %s is %s\n", path, _truename(path, (char *)0));
@end example

@c -----------------------------------------------------------------------------
@node _truename_sfn, truncate, _truename, Alphabetical List
@unnumberedsec _truename_sfn
@c From file ./dos/dos/truename.txh
@findex _truename_sfn
@subheading Syntax

@example
#include <sys/stat.h>

char * _truename_sfn(const char *path, char *true_path);
@end example

@subheading Description

@code{_truename_sfn} is like @code{_truename}, except that it always
returns a short filename. See the documentation for @code{_truename}
for more details (@pxref{_truename}).

@subheading Return Value

The function returns the pointer to the result.  In case of any failure,
a NULL pointer is returned, and @code{errno} is set.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
  fprintf(stderr, 
          "True short name of %s is %s\n", path,
	  _truename_sfn(path, (char *)0));
@end example
@c -----------------------------------------------------------------------------
@node truncate, ttyname, _truename_sfn, Alphabetical List
@unnumberedsec truncate
@c From file ./compat/unistd/truncate.txh
@findex truncate
@subheading Syntax

@example
#include <unistd.h>

int truncate(const char *file, off_t size);
@end example

@subheading Description

This function truncates @var{file} to @var{size} bytes.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
truncate("/tmp/data.txt", 400);
@end example

@c -----------------------------------------------------------------------------
@node ttyname, tzset, truncate, Alphabetical List
@unnumberedsec ttyname
@c From file ./posix/unistd/ttyname.txh
@findex ttyname
@subheading Syntax

@example
#include <unistd.h>

char *ttyname(int file);
@end example

@subheading Description

Gives the name of the terminal associated with @var{file}. 

@subheading Return Value

Returns "con" if @var{file} is a device, else @code{NULL}.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
char *tty = ttyname(0);
@end example

@c -----------------------------------------------------------------------------
@node tzset, tzsetwall, ttyname, Alphabetical List
@unnumberedsec tzset
@c From file ./ansi/time/ctime.txh
@vindex tzname
@findex tzset
@vindex TZ@r{ environment variable, and }tzname
@subheading Syntax

@example
#include <time.h>

extern char *tzname[2];
void tzset(void);
@end example

@subheading Description

This function initializes the global variable @code{tzname} according to
environment variable @code{TZ}.  After the call, @code{tzname} holds the
specifications for the time zone for the standard and daylight-saving
times.

@subheading Return Value

None.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable



@c -----------------------------------------------------------------------------
@node tzsetwall, uclock, tzset, Alphabetical List
@unnumberedsec tzsetwall
@c From file ./ansi/time/ctime.txh
@findex tzsetwall
@subheading Syntax

@example
#include <time.h>

void tzsetwall(void);
@end example

@subheading Description

This function sets up the time conversion information used by
@code{localtime} (@pxref{localtime}) so that @code{localtime} returns
the best available approximation of the local wall clock time.

@subheading Return Value

None.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable

@c -----------------------------------------------------------------------------
@node uclock, umask, tzsetwall, Alphabetical List
@unnumberedsec uclock
@c From file ./pc_hw/timer/uclock.txh
@findex uclock
@subheading Syntax

@example
#include <time.h>

uclock_t uclock(void);
@end example

@subheading Description

This function returns the number of uclock ticks since an arbitrary time,
actually, since the first call to @code{uclock}, which itself returns
zero.  The number of tics per second is @code{UCLOCKS_PER_SEC} (declared
in the @file{time.h} header file.

@code{uclock} is provided for very high-resolution timing.  It is
currently accurate to better than 1 microsecond (actually about 840
nanoseconds).  You cannot time across two midnights with this
implementation, giving a maximum useful period of 48 hours and an
effective limit of 24 hours.  Casting to a 32-bit integer limits its
usefulness to about an hour before 32 bits will wrap.

Note that @code{printf} will only print a value of type @code{uclock_t}
correctly if you use the format specifier for @code{long long} data,
@code{%lld}, because @code{uclock_t} is a 64-bit integer.
@xref{printf}.

Also note that @code{uclock} reprograms the interval timer in your PC
to act as a rate generator rather than a square wave generator.  I've
had no problems running in this mode all the time, but if you notice
strange things happening with the clock (losing time) after using
@code{uclock}, check to see if this is the cause of the problem.

Windows 3.X doesn't allow to reprogram the timer, so the values returned
by @code{uclock} there are incorrect.  DOS and Windows 9X don't have
this problem.

Windows NT, 2000 and XP attempt to use the @code{rdtsc} feature of newer
CPUs instead of the interval timer, because the timer tick and interval timer 
are not coordinated.  During calibration the @code{SIGILL} signal handler
is replaced to protect against systems which do not support or allow 
@code{rdtsc}.  If @code{rdtsc} is available, uclock will keep the upper
bits of the returned value consistent with the bios tick counter by 
re-calibration if needed.  If @code{rdtsc} is not available, these systems 
fall back to interval timer usage, which may show an absolute error of 65536 
uclock ticks in the values and not be monotonically increasing.

@subheading Return Value

The number of tics.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
printf("%lld ticks have elapsed\n", (long long)(uclock()));
printf("%f second have elapsed\n",
       ((double)uclock()/UCLOCKS_PER_SEC));
@end example

@c -----------------------------------------------------------------------------
@node umask, uname, uclock, Alphabetical List
@unnumberedsec umask
@c From file ./posix/sys/stat/umask.txh
@findex umask
@subheading Syntax

@example
#include <sys/stat.h>

mode_t umask(mode_t cmask);
@end example

@subheading Description

This function does nothing.  It exists to assist porting.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node uname, ungetc, umask, Alphabetical List
@unnumberedsec uname
@c From file ./posix/utsname/uname.txh
@findex uname
@tindex utsname@r{ structure}
@subheading Syntax

@example
#include <sys/utsname.h>

int uname(struct utsname *u);
@end example

@subheading Description

Fills in the structure with information about the system.  

@example
struct utsname @{
  char machine[9];
  char nodename[32];
  char release[9];
  char sysname[9];
  char version[9];
@};
@end example

@table @code

@item machine
The CPU family type: @code{"i386"}, @code{"i486"}, @code{"i586"}
(Pentium), @code{"i686"} (PentiumPro, Pentium II, Pentium III), or
@code{"i786"} (Pentium 4).

@item nodename
The name of your PC (if networking is installed), else @code{"pc"}.

@item release
The major version number of DOS.  For example, DOS 1.23 would return
@code{"1"} here.

@item sysname
The flavor of the OS.  

@item version
The minor version number of DOS.  For example, DOS 1.23 would return
@code{"23"} here.
@end table

@subheading Return Value

Zero on success, else nonzero.  

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable

@c -----------------------------------------------------------------------------
@node ungetc, ungetch, uname, Alphabetical List
@unnumberedsec ungetc
@c From file ./ansi/stdio/ungetc.txh
@findex ungetc
@subheading Syntax

@example
#include <stdio.h>

int ungetc(int c, FILE *file);
@end example

@subheading Description

This function pushes @var{c} back into the @var{file}.  You can only
push back one character at a time. 

@subheading Return Value

The pushed-back character, or @code{EOF} on error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
int q;
while (q = getc(stdin) != 'q');
ungetc(q);
@end example

@c -----------------------------------------------------------------------------
@node ungetch, unlink, ungetc, Alphabetical List
@unnumberedsec ungetch
@c From file ./pc_hw/co80/conio.txh
@findex ungetch
@subheading Syntax

@example
#include <conio.h>

int ungetch(int);
@end example

@subheading Description

Puts a character back, so that @code{getch} (@pxref{getch}) will return
it instead of actually reading the console.

@subheading Return Value

The character is returned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node unlink, unlock, ungetch, Alphabetical List
@unnumberedsec unlink
@c From file ./posix/unistd/unlink.txh
@findex unlink
@subheading Syntax

@example
#include <unistd.h>

int unlink(const char *file);
@end example

@subheading Description

This function removes a file from the file system. 

@subheading Return Value

Zero on success, nonzero on failure. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992 (partial); 1003.1-2001 (partial); 1003.1-2008 (partial); (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
The @sc{posix} specification requires this removal to be delayed until the
file is no longer open.  Due to problems with the underlying operating
systems, this implementation of @code{unlink} does not fully comply with
the specs; if the file you want to unlink is open, you're asking for
trouble --- how much trouble depends on the underlying OS.  On Windows NT
(and possibly on Windows 2000 as well), you get the behaviour @sc{posix}
expects.
On Windows 9x and Windows ME (and possibly Windows XP as well), the removal
will simply fail (@code{errno} gets set to @code{EACCES}).  On DOS, removing
an open file could lead to filesystem corruption if the removed file is
written to before it's closed.
@end enumerate

@subheading Example

@example
unlink("data.txt");
@end example
@c -----------------------------------------------------------------------------
@node unlock, unlock64, unlink, Alphabetical List
@unnumberedsec unlock
@c From file ./dos/io/unlock.txh
@findex unlock
@subheading Syntax

@example
#include <io.h>

int unlock(int fd, long offset, long length);
@end example

@subheading Description
Unlocks a region previously locked by @code{lock}.

@xref{lock}.

@subheading Return Value
Zero if successful, nonzero if not.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node unlock64, unsetenv, unlock, Alphabetical List
@unnumberedsec unlock64
@c From file ./dos/io/unlock64.txh
@findex unlock64
@subheading Syntax

@example
#include <io.h>

int unlock64(int fd, long long offset, long long length);
@end example

@subheading Description
Unlocks a region previously locked by @code{lock64}.

Arguments @var{offset} and @var{length} must be of type @code{long
long}, thus enabling you to unlock with offsets and lengths as large as
~@math{2^63} (FAT16 limits this to ~@math{2^31}; FAT32 limits this to
@math{2^32-2}).

@xref{lock64}.

@subheading Return Value
Zero if successful, nonzero if not.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node unsetenv, _use_lfn, unlock64, Alphabetical List
@unnumberedsec unsetenv
@c From file ./posix/stdlib/unsetenv.txh
@findex unsetenv
@subheading Syntax

@example
#include <stdlib.h>

int unsetenv(const char *name);
@end example

@subheading Description

This function removes the environment variable @var{name} from the
environment.  This will update the list of pointers to which the
@var{environ} variable points.
If the specified variable does not exist in the environment, the
environment is not modified and this function is considered to have
been sucessfully completed.

@subheading Return Value

If @var{name} is @code{NULL}, points to an empty string, or points to
a string containing a @samp{=}, this function returns -1 and sets
@code{errno} to @code{EINVAL}; otherwise it returns 0.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
This function is new to the Posix 1003.1-200x draft
@end enumerate
@c -----------------------------------------------------------------------------
@node _use_lfn, usleep, unsetenv, Alphabetical List
@unnumberedsec _use_lfn
@c From file ./dos/lfn/_use_lfn.txh
@findex _use_lfn
@vindex LFN@r{ environment variable}
@subheading Syntax
 
@example
#include <fcntl.h>
 
char _use_lfn(const char *path);
@end example
 
@subheading Description
 
The @code{_use_lfn} function returns a nonzero value if the low level
libc routines will use the @dfn{Long File Name} (LFN) functions provided
with Windows 9x (and other advanced filesystems), when accessing files
and directories on the same filesystem as @var{path}.  @var{path} may be
any legal pathname; however, the function only needs the name of the
root directory on the particular drive in question.  If @var{path} is a
@code{NULL} pointer, the function assumes that all the filesystems
support (or do not support) LFN in the same manner, and returns the info
pertinent to the last filesystem that was queried; this usually makes
the call faster.  Note that on Windows 95 you don't need to distinguish
between different drives: they all support LFN API.  If @var{path} does
not specify the drive explicitly, the current drive is used.

The header @file{fcntl.h} defines a macro @code{_USE_LFN}; applications
should use this macro instead of calling @code{_use_lfn} directly.  That
is so this routine could be replaced with one which always returns 0 to
disable using long file names.  Calling @code{_USE_LFN} also makes the
code more portable to other operating systems, where the macro can be
redefined to whatever is appropriate for that environment (e.g., it
should be a constant 1 on Unix systems and constant 0 for environments
that don't support LFN API, like some other MSDOS compilers).
Currently, @code{_USE_LFN} assumes that LFN API does @emph{not} depend
on a drive.

Long file names can also be disabled by setting the flag
@code{_CRT0_FLAG_NO_LFN} in @code{_crt0_startup_flags} for an image
which should not allow use of long file names.  Long names can be
suppressed at runtime on a global basis by setting the environment
variable @code{LFN} to @code{N}, i.e. @samp{SET LFN=N}.  This might be
needed if a distribution expected the truncation of long file names to
8.3 format to work.  For example, if a C source routine included the
file exception.h (9 letters) and the file was unzipped as exceptio.h,
then GCC would not find the file unless you set @samp{LFN=n}.  The
environment variable can be set in the @file{DJGPP.ENV} file to always
disable LFN support on any system, or can be set in the DOS environment
for a short term (single project) basis.  If you dual boot a system
between Windows 95 and DOS, you probably should set @samp{LFN=n} in your
@file{DJGPP.ENV} file, since long file names would not be visible under
DOS, and working with the short names under DOS will damage the long
names when returning to Windows 95.

@subheading Return Value
 
If LFN APIs are supported and should be used, it returns 1, else 0.

Note that if the @code{_CRT0_FLAG_NO_LFN} bit is set, or @code{LFN} is
set to @code{N} or @code{n} in the environment, both @code{_use_lfn} and
@code{_USE_LFN} will always return 0 without querying the filesystem.
You can reset the @code{_CRT0_FLAG_NO_LFN} bit at runtime to force
filesystem to be queried.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example

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

  int fd = creat (_USE_LFN ? "MyCurrentJobFile.Text" : "currjob.txt",
                  S_IRUSR | S_IWUSR);

@end example


@c -----------------------------------------------------------------------------
@node usleep, utime, _use_lfn, Alphabetical List
@unnumberedsec usleep
@c From file ./compat/unistd/usleep.txh
@findex usleep
@subheading Syntax

@example
#include <unistd.h>

unsigned usleep(unsigned usec);
@end example

@subheading Description

This function pauses the program for @var{usec} microseconds.  Note
that, since @code{usleep} calls @code{clock} internally, and the latter
has a 55-msec granularity, any argument less than 55@dmn{msec} will result in
a pause of random length between 0 and 55 msec.  Any argument less
than 11@dmn{msec} (more precisely, less than 11264 microseconds), will always
result in zero-length pause (because @code{clock} multiplies the timer
count by 5).  @xref{clock}.

@subheading Return Value

The number of unslept microseconds (i.e. zero).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
usleep(500000);
@end example

@c -----------------------------------------------------------------------------
@node utime, utimes, usleep, Alphabetical List
@unnumberedsec utime
@c From file ./posix/utime/utime.txh
@findex utime
@tindex utimbuf@r{ structure}
@subheading Syntax

@example
#include <utime.h>

int utime(const char *file, const struct utimbuf *time);
@end example

@subheading Description

This function sets the modification timestamp on the @var{file}.  The
new time is stored in this structure:

@example
struct utimbuf
@{
    time_t  actime;  /* access time (unused on FAT filesystems) */
    time_t  modtime; /* modification time */
@};
@end example

Note that, as under DOS a file only has a single timestamp, the
@code{actime} field of @code{struct utimbuf} is ignored by this
function, and only @code{modtime} field is used.  On filesystems which
support long filenames, both fields are used and both access and
modification times are set.

If @var{file} is a directory, the function always fails, except on
Windows 2000 and Windows XP, because other systems don't allow changing
the time stamp of a directory.

@subheading Return Value

Zero for success, nonzero for failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
struct utimbuf t;
t.modtime = time(0);
utime("data.txt", &t);
@end example

@c -----------------------------------------------------------------------------
@node utimes, v2loadimage, utime, Alphabetical List
@unnumberedsec utimes
@c From file ./compat/time/utimes.txh
@findex utimes
@subheading Syntax

@example
#include <sys/time.h>

int utimes(const char *file, struct timeval tvp[2]);
@end example

@subheading Description

This function sets the file access time as specified by
@code{@var{tvp}[0]}, and its modification time as specified by
@code{@var{tvp}[1]}.  @code{struct timeval} is defined as follows:

@example
struct timeval @{
  time_t tv_sec;
  long tv_usec;
@};
@end example

Note that DOS and Windows maintain the file times with 2-second
granularity.  Therefore, the @code{tv_usec} member of the argument is
always ignored, and the underlying filesystem truncates (or sometimes
rounds) the actual file time stamp to the multiple of 2 seconds.

On plain DOS, only one file time is maintained, which is arbitrarily
taken from @code{@var{tvp}[1].tv_sec}.  On Windows 9X, both times are
used, but note that most versions of Windows only use the date part and
ignore the time.

Due to limitations of DOS and Windows, you cannot set times of
directories.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
time_t now;
struct timeval tvp[2];
time(&now);
tvp[1].tv_sec = now + 100;
utimes("foo.dat", tvp);
@end example

@c -----------------------------------------------------------------------------
@node v2loadimage, valloc, utimes, Alphabetical List
@unnumberedsec v2loadimage
@c From file ./debug.txh
@findex v2loadimage

@subheading Syntax

@example
#include <debug/v2load.h>

int v2loadimage (const char *program, const char *cmdline,
                 jmp_buf load_state);
@end example

@subheading Description

This function loads an executable image of a DJGPP v2.x program and
prepares it for debugging.  @var{program} should point to the file name
of the executable program.  @code{v2loadimage} does @strong{not} search
the @code{PATH} and does @strong{not} try any executable extensions, so
@var{program} should point to a fully-qualified path, complete with the
drive, directory, and file-name extension; otherwise the call will fail.

@var{cmdline} should point to the command-line arguments to be passed to
the program.  A command line up to 126 characters long can be formatted
exactly like the command tail DOS passes to programs: the first byte gives
the length of the command tail, the tail itself begins with the second byte,
and the tail is terminated by a CR character (decimal code 13); the length
byte does not include the CR.  Longer command lines require a different
format: the first byte is 255, the command-line starting with the second byte
which is terminated by a NUL character (decimal code 0).  Regardless of the
method used, the command-line arguments should look as if they were to be
passed to the library function @code{system}.  In particular, all special
characters like wildcards and whitespace should be quoted as if they were
typed at the DOS prompt.

After the function loads the image and sets up the necessary memory
segments for it to be able to run, it sets @var{load_state} so that it
can be used to @code{longjmp} to the debuggee's entry point.  This
information is typically used by @code{run_child} (@pxref{run_child}).

@subheading Return Value

Zero in case of success, non-zero otherwise.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
 cmdline = (char *) alloca (strlen (args) + 4);
 cmdline[0] = strlen (args);
 strcpy (cmdline + 1, args);
 cmdline[strlen (args) + 1] = 13;

 if (v2loadimage (exec_file, cmdline, start_state))
  @{
    printf ("Load failed for image %s\n", exec_file);
    exit (1);
  @}

  edi_init (start_state);
@end example


@c -----------------------------------------------------------------------------
@node valloc, varargs, v2loadimage, Alphabetical List
@unnumberedsec valloc
@c From file ./compat/stdlib/valloc.txh
@findex valloc
@subheading Syntax

@example
#include <stdlib.h>

void *valloc(size_t size);
@end example

@subheading Description

This function is just like @code{malloc} (@pxref{malloc}) except the returned
pointer is a multiple of the CPU page size which is 4096 bytes.

@subheading Return Value

A pointer to a newly allocated block of memory. 

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char *page = valloc(getpagesize());
@end example
@c -----------------------------------------------------------------------------
@node varargs, vasnprintf, valloc, Alphabetical List
@unnumberedsec varargs
@c From file ./ansi/stdarg/va_.txh
@findex va_start
@findex va_arg
@findex va_end
@subheading Syntax

@example

#include <stdarg.h>

void va_start(va_list ap, LAST_REQUIRED_ARG);
TYPE va_arg(va_list ap, TYPE);
void va_end(va_list ap);

@end example

@subheading Description

Used to write functions taking a variable number of arguments.  Note
that these are actually macros, and not functions.  You must prototype
the function with `@dots{}' in its argument list.  Then, you do the
following:

@itemize @bullet
@item

Create a variable of type @code{va_list}.

@item

Initialize it by calling @code{va_start} with it and the name of the
last required (i.e. non-variable) argument.

@item

Retrieve the arguments by calling @code{va_arg} with the
@code{va_list} variable and the type of the argument.  As another
alternative, you can pass the @code{va_list} to another function,
which may then use @code{va_arg} to get at the arguments.
@code{vprintf} is an example of this.

@item

Call @code{va_end} to destroy the @code{va_list}.

@end itemize

Be aware that your function must have some way to determine the number
and types of the arguments.  Usually this comes from one of the required
arguments.  Some popular ways are to pass a count, or to pass some
special value (like @code{NULL}) at the end.

Also, the variable arguments will be promoted according to standard C
promotion rules.  Arguments of type @code{char} and @code{short} will
be promoted to @code{int}, and you should retrieve them as such.  Those
of type @code{float} will be promoted to @code{double}.

@subheading Return Value

@code{va_arg} returns the argument it fetched, the other macros return nothing.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example

int find_the_sum(int count, @dots{})
@{
  va_list ap;
  int i;
  int total = 0;
  
  va_start(ap, count);
  for (i = 0; i < count; i++)
      total += va_arg(ap, int);
  va_end(ap);
  return total;
@}

int other_function(void)
@{
  return find_the_sum(6, 1, 2, 3, 4, 5, 6);
@} 

@end example
@c -----------------------------------------------------------------------------
@node vasnprintf, vasprintf, varargs, Alphabetical List
@unnumberedsec vasnprintf
@c From file ./compat/stdio/vasnprtf.txh
@findex vasnprintf
@subheading Syntax

@example
#include <stdio.h>
#include <stdarg.h>

char *vasnprintf(char *buffer, size_t *np, const char *format, va_list ap);
@end example

@subheading Description

Sends formatted output from the arguments in (@var{ap}) including
the terminating null byte to a string buffer and returns a pointer
to it.  This buffer can be preallocated and passed to the function
via @var{buffer}.  The buffer length must be passed by @var{np}.  The
function will write up to *@var{np} - 1 characters.  The *@var{np}th
character is used for the terminating nul.  Upon error, @code{errno}
is set and a @code{NULL} pointer is returned.

If @var{buffer} is a @code{NULL} pointer or *@var{np} is zero, a string
buffer is allocated and returned by the function on success.  If dynamic
allocation occurs, the preallocated buffer is left alone (with possibly
modified contents).  The length of the newly allocated string buffer is
returned by the function via the @var{np} pointer.  The allocated memory
must be returned to the heap with @code{free} (@pxref{free}). 

@subheading Return Value

If dynamic allocation occurs, a pointer to the newly allocated string buffer
is returned else @var{buffer}.  The number of characters that would have been
written (excluding the trailing nul) is returned by @var{np}; otherwise the
function returns a @code{NULL} pointer.

The maximum accepted value of *@var{np} is @code{INT_MAX}.  @code{INT_MAX} is
defined in @code{<limits.h>}.  A @code{NULL} pointer is returned and @code{errno}
is set to @code{EFBIG}, if *@var{np} is greater than this limit.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No (see note 1)
@item POSIX
@tab No
@end multitable

@noindent
Notes:

@enumerate
@item
The buffer size limit is imposed by DJGPP.  Other systems may not have this limitation.

@end enumerate

@subheading Example

@example
char *result;
char string[100];  /*  Preallocated buffer passed to vasnprintf.  */
int len = 100;

result = vasnprintf(string, &len, "arg[0] = %s\n"
                                  "arg[1] = %s\n"
                                  "arg[2] = %s\n", arg_list);

if (!result)
  printf("error: vasnprintf failed.\n");
else
@{
  /*
   *  Your code using the buffer allocated by vasnprintf.
   */
  do_something(result);
  if (result != string)
    free(result);  /*  Allocation had happened; release the buffer allocated by vasnprintf.  */
@}
@end example
@c -----------------------------------------------------------------------------
@node vasprintf, vdprintf, vasnprintf, Alphabetical List
@unnumberedsec vasprintf
@c From file ./compat/stdio/vasprntf.txh
@findex vasprintf
@subheading Syntax

@example
#include <stdio.h>
#include <stdarg.h>

int vasprintf(char **bufferp, const char *format, va_list ap);
@end example

@subheading Description

Sends formatted output from the arguments in (@var{ap}) including
the terminating null byte to the allocated buffer and returns
a pointer to it via the first parameter *@var{bufferp}.  This
memory must be returned to the heap with @code{free} (@pxref{free}). 
This function is analog of @code{vsprintf()} (@pxref{vsprintf}).

@subheading Return Value

The number of characters that would have been written (excluding
the terminating null byte) is returned; otherwise EOF is returned
to flag encoding or buffer space errors and the pointer
*@var{bufferp} is set to @code{NULL}.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char *strbuf;  /*  Pointer to the buffer allocated by vasprintf.  */
int strlng;

strlng = vasprintf(&strbuf, "arg[0] = %s\n"
                            "arg[1] = %s\n"
                            "arg[2] = %s\n", arg_list);

if (EOF == strlng)
  printf("error: vasprintf failed.\n");
else
@{
  /*
   *  Your code using the buffer allocated by vasprintf.
   */
  do_something(strbuf, strlng);

  free(strbuf);  /*  Release the buffer allocated by vasprintf.  */
@}
@end example
@c -----------------------------------------------------------------------------
@node vdprintf, vfork, vasprintf, Alphabetical List
@unnumberedsec vdprintf
@c From file ./posix/stdio/vdprintf.txh
@findex vdprintf
@subheading Syntax

@example
#include <stdio.h>

int vdprintf(int file_desc, const char *format, va_list arguments);
@end example

@subheading Description

The function @code{vdprintf} is an exact analog of @code{vfprintf} (@pxref{vfprintf}),
except that it output to a file descriptor @var{file_desc}
instead of to a stdio stream.

@subheading Return Value

The number of characters written is returned; otherwise EOF
is returned to flag encoding or buffer space errors.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable

@c -----------------------------------------------------------------------------
@node vfork, vfprintf, vdprintf, Alphabetical List
@unnumberedsec vfork
@c From file ./compat/unistd/vfork.txh
@findex vfork
@subheading Syntax

@example
#include <unistd.h>

pid_t vfork(void);
@end example

@subheading Description

This function always returns -1 and sets `errno' to ENOMEM, as MS-DOS
does not support multiple processes.  It exists only to assist in
porting Unix programs.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node vfprintf, vfscanf, vfork, Alphabetical List
@unnumberedsec vfprintf
@c From file ./ansi/stdio/vfprintf.txh
@findex vfprintf
@subheading Syntax

@example
#include <stdio.h>
#include <stdarg.h>

int vfprintf(FILE *file, const char *format, va_list arguments);
@end example

@subheading Description

Sends formatted output from the @var{arguments} to the @var{file}. 
@xref{printf}.

@subheading Return Value

The number of characters written.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
void my_errmsg(char *format, ...)
@{
  va_list arg;

  va_start(arg, format);
  fprintf(stderr, "my_errmsg: ");
  vfprintf(stderr, format, arg);
  va_end(arg);
@}
@end example
@c -----------------------------------------------------------------------------
@node vfscanf, vprintf, vfprintf, Alphabetical List
@unnumberedsec vfscanf
@c From file ./compat/stdio/vfscanf.txh
@findex vfscanf
@subheading Syntax

@example
#include <stdio.h>

int vfscanf(FILE *file, const char *format, va_list arguments);
@end example

@subheading Description

This function scans formatted text from @var{file} and stores it in the
variables pointed to by the @var{arguments}.  @xref{scanf}.

@subheading Return Value

The number of items successfully scanned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node vprintf, vscanf, vfscanf, Alphabetical List
@unnumberedsec vprintf
@c From file ./ansi/stdio/vprintf.txh
@findex vprintf
@subheading Syntax

@example
#include <stdio.h>
#include <stdarg.h>

int vprintf(const char *format, va_list arguments);
@end example

@subheading Description

Sends formatted output from the @var{arguments} to @code{stdout}. 
@xref{printf}. @xref{vfprintf}.

@subheading Return Value

The number of characters written.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node vscanf, vsnprintf, vprintf, Alphabetical List
@unnumberedsec vscanf
@c From file ./compat/stdio/vscanf.txh
@findex vscanf
@subheading Syntax

@example
#include <stdio.h>

int vscanf(const char *format, va_list arguments);
@end example

@subheading Description

This function scans formatted text from @code{stdin} and stores it in the
variables pointed to by the @var{arguments}. @xref{scanf}.
@xref{vfscanf}.

@subheading Return Value

The number of items successfully scanned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node vsnprintf, vsprintf, vscanf, Alphabetical List
@unnumberedsec vsnprintf
@c From file ./ansi/stdio/vsnprntf.txh
@findex vsnprintf
@subheading Syntax

@example
#include <stdio.h>
#include <stdarg.h>

int vsnprintf (char *buffer, size_t n, const char *format, va_list ap);
@end example

@subheading Description

This function works similarly to @code{vsprintf()} (@pxref{vsprintf}), but
the size @var{n} of the @var{buffer} is also taken into account.  This
function will write @var{n} - 1 characters.  The @var{n}th character is used
for the terminating nul.  If @var{n} is zero, @var{buffer} is not touched.

@subheading Return Value

The number of characters that would have been written (excluding the trailing
nul) is returned; otherwise -1 is returned to flag encoding or buffer space
errors.

The maximum accepted value of @var{n} is @code{INT_MAX}.  @code{INT_MAX} is
defined in @code{<limits.h>}.  -1 is returned and @code{errno} is set to
@code{EFBIG}, if @var{n} is greater than this limit.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99; (see note 1)
@end multitable

@noindent
Notes:

@enumerate
@item
The buffer size limit is imposed by DJGPP.  Other systems may not have this limitation.

@end enumerate
@c -----------------------------------------------------------------------------
@node vsprintf, vsscanf, vsnprintf, Alphabetical List
@unnumberedsec vsprintf
@c From file ./ansi/stdio/vsprintf.txh
@findex vsprintf
@subheading Syntax

@example
#include <stdio.h>
#include <stdarg.h>

int vsprintf(char *buffer, const char *format, va_list arguments);
@end example

@subheading Description

Sends formatted output from the @var{arguments} to the @var{buffer}.
@xref{printf}. @xref{vfprintf}.

To avoid buffer overruns, it is safer to use @code{vsnprintf()}
(@pxref{vsnprintf}).

@subheading Return Value

The number of characters written.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node vsscanf, wait, vsprintf, Alphabetical List
@unnumberedsec vsscanf
@c From file ./compat/stdio/vsscanf.txh
@findex vsscanf
@subheading Syntax

@example
#include <stdio.h>

int vsscanf(const char *string, const char *format, va_list arguments);
@end example

@subheading Description

This function scans formatted text from the @var{string} and stores it
in the variables pointed to by the @var{arguments}. @xref{scanf}.
@xref{vfscanf}.

@subheading Return Value

The number of items successfully scanned.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node wait, waitpid, vsscanf, Alphabetical List
@unnumberedsec wait
@c From file ./posix/sys/wait/wait.txh
@findex wait
@subheading Syntax

@example
#include <sys/wait.h>

pid_t pid = wait(int *status);
@end example

@subheading Description

This function causes its caller to delay its execution until a signal
is received or one of its child processes terminates.  If any child has
terminated, return is immediate, returning the process ID and its exit
status, if that's available.  If no children processes were called since
the last call, then -1 is returned and @code{errno} is set.

@subheading Return Value

If successful, this function returns the exit status of the child.  If
there is an error, these functions return -1 and set @code{errno} to
indicate the error type.

@subheading Bugs

Currently, this function always fails.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node waitpid, wcstombs, wait, Alphabetical List
@unnumberedsec waitpid
@c From file ./posix/sys/wait/wait.txh
@findex waitpid
@subheading Syntax

@example
#include <sys/wait.h>

pid_t pid = waitpid((pid_t pid, int *status, int options);
@end example

@subheading Description

Currently, this function always fails. A -1 is returned and @code{errno}
is set to indicate there are no children.

@subheading Return Value

If successful, this function returns the exit status of the child.  If
there is an error, these functions return -1 and set @code{errno} to
indicate the error type.

@subheading Bugs

Currently, this function always fails.


@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@c -----------------------------------------------------------------------------
@node wcstombs, wctomb, waitpid, Alphabetical List
@unnumberedsec wcstombs
@c From file ./ansi/locale/wcstombs.txh
@findex wcstombs
@subheading Syntax

@example
#include <stdlib.h>

size_t wcstombs(char *s, const wchar_t *wcs, size_t n);
@end example

@subheading Description

Converts a wide character string to a multibyte string.  At most
@var{n} characters are stored.

@subheading Return Value

The number of characters stored.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
int len = wcstombs(buf, wstring, sizeof(buf));
@end example

@c -----------------------------------------------------------------------------
@node wctomb, wherex, wcstombs, Alphabetical List
@unnumberedsec wctomb
@c From file ./ansi/locale/wctomb.txh
@findex wctomb
@subheading Syntax

@example
#include <stdlib.h>

int wctomb(char *s, wchar_t wchar);
@end example

@subheading Description

Convert a wide character to a multibyte character.  The string @var{s}
must be at least @code{MB_LEN_MAX} bytes long.

@subheading Return Value

The number of characters stored.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab C89; C99
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

@example
char s[MB_LEN_MAX];
int mlen = wctomb(s, wc);
@end example

@c -----------------------------------------------------------------------------
@node wherex, wherey, wctomb, Alphabetical List
@unnumberedsec wherex
@c From file ./pc_hw/co80/conio.txh
@findex wherex
@subheading Syntax

@example
#include <conio.h>

int wherex(void);
@end example

@subheading Return Value

The column the cursor is on.  The leftmost column is 1.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node wherey, wild, wherex, Alphabetical List
@unnumberedsec wherey
@c From file ./pc_hw/co80/conio.txh
@findex wherey
@subheading Syntax

@example
#include <conio.h>

int     wherey(void);
@end example

@subheading Return Value

The row the cursor is on.  The topmost row is 1.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node wild, window, wherey, Alphabetical List
@unnumberedsec wild
@c From file ./debug.txh
@findex wild

@subheading Syntax

@example
#include <debug/wild.h>

int wild (char *pattern, char *string);
@end example

@subheading Description

This function matches a string pointed to by @var{string} against a
pattern pointed to by @var{pattern}.  @var{pattern} may include wildcard
characters @samp{?} and @samp{*}, meaning, respectively, any single
character and any string of characters.  The function returns non-zero
if the string matches the pattern, zero otherwise.

This function is meant to be used for simple matching of patterns, such
as if a debugger needs to allow specification of symbols using
wildcards.

@subheading Return Value

The function returns non-zero if the string matches the pattern, zero
otherwise.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable



@c -----------------------------------------------------------------------------
@node window, write, wild, Alphabetical List
@unnumberedsec window
@c From file ./pc_hw/co80/conio.txh
@findex window
@subheading Syntax

@example
#include <conio.h>

void    window(int _left, int _top, int _right, int _bottom);
@end example

@subheading Description

Specifies the window on the screen to be used for future output
requests.  The upper left corner of the physical screen is (1,1).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Implementation Note

It's not safe to call this function inside static constructors, because
conio needs to be initialized, and its initialization is done by a
static constructor.  Since you don't have any control on the order in
which static constructors are called (it's entirely up to the linker),
you could have problems.

If you can detect the situation when one of the conio functions is
called for the very first time since program start, you could work
around this problem by calling the @code{gppconio_init} function
manually (this is the function called by a static constructor).

@c -----------------------------------------------------------------------------
@node write, _write, window, Alphabetical List
@unnumberedsec write
@c From file ./posix/unistd/write.txh
@findex write
@subheading Syntax

@example
#include <unistd.h>

int write(int file, const void *buffer, size_t count);
@end example

@subheading Description

This function writes @var{count} bytes from @var{buffer} to
@var{file}.  It returns the number of bytes actually written.  It will
return zero or a number less than @var{count} if the disk is full, and
may return less than @var{count} even under valid conditions.

Note that if @var{file} is a text file, @code{write} may write more
bytes than it reports. 

If @var{count} is zero, the function does nothing and returns zero.
Use @code{_write} if you want to actually ask DOS to write zero bytes.

The precise behavior of @code{write} when the target filesystem is full
is somewhat troublesome, because DOS doesn't fail the underlying system
call.  If your application needs to rely on @code{errno} being set to
@code{ENOSPC} in such cases, you need to invoke @code{write} as shown in
the example below.  In a nutshell, the trick is to call @code{write} one
more time after it returns a value smaller than the @var{count}
parameter; then it will @emph{always} set @code{errno} if the disk is
full.

@subheading Return Value

The number of bytes written, zero at EOF, or -1 on error.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.2-1992; 1003.1-2001; 1003.1-2008
@end multitable


@subheading Example

This example shows how to call @code{write} in a way which ensures that
@code{errno} will be set to @code{ENOSPC} if the target filesystem is or
becomes full:

@example
  char *buf_ptr;    /* the buffer to write */
  size_t buf_len;   /* the number of bytes to write */
  int desc;         /* the file descriptor to write to */

  while (buf_len > 0)
  @{
    int written = write (desc, buf_ptr, buf_len);
    if (written <= 0)
      break;

    buf_ptr += written;
    buf_len -= written;
  @}
@end example

@c -----------------------------------------------------------------------------
@node _write, write_child, write, Alphabetical List
@unnumberedsec _write
@c From file ./dos/io/_write.txh
@findex _write
@subheading Syntax

@example
#include <io.h>

ssize_t _write(int fildes, const void *buf, size_t nbyte);
@end example

@subheading Description

This is a direct connection to the MS-DOS write function call, int
0x21, %ah = 0x40.  No conversion is done on the data; it is written as
raw binary data.  This function can be hooked by the File-system
extensions, see @ref{File System Extensions}.  If you don't want this,
you should use @code{_dos_write} instead, see @ref{_dos_write}.

@subheading Return Value

The number of bytes written, or -1 (and @code{errno} set) in case of
failure.

Note that DOS doesn't return an error indication when the target disk is
full; therefore if the disk fills up while the data is written,
@code{_write} does @strong{not} return -1, it returns the number of
bytes it succeeded to write.  If you need to detect the disk full
condition reliably, call @code{_write} again to try to write the rest of
the data.  This will cause DOS to return zero as the number of written
bytes, and @emph{then} @code{_write} will return -1 and set @code{errno}
to @code{ENOSPC}.  The example below shows one way of doing this.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

This example shows how to call @code{_write} in a way which ensures that
@code{errno} will be set to @code{ENOSPC} if the target filesystem is or
becomes full:

@example
  char *buf_ptr;    /* the buffer to write */
  size_t buf_len;   /* the number of bytes to write */
  int desc;         /* the file descriptor to write to */

  while (buf_len > 0)
  @{
    int written = _write (desc, buf_ptr, buf_len);
    if (written <= 0)
      break;

    buf_ptr += written;
    buf_len -= written;
  @}
@end example

@c -----------------------------------------------------------------------------
@node write_child, write_sel_addr, _write, Alphabetical List
@unnumberedsec write_child
@c From file ./debug.txh
@findex write_child

@subheading Syntax

@example
#include <debug/dbgcom.h>

int write_child (unsigned child_addr, void *buf, unsigned len);
@end example

@subheading Description

This function transfers @var{len} bytes from the buffer pointed to by
@var{buf} in the debugger's data segment to the memory of the debugged
process starting at the address @var{child_addr}.  It is used primarily
to insert a breakpoint instruction into the debugged process (to trigger
a trap when the debuggee's code gets to that point).  The companion
function @code{read_child} (@pxref{read_child}) is usually called before
@code{write_child} to save the original code overwritten by the
breakpoint instruction.

@subheading Return Value

The function return zero if it has successfully transferred the data,
non-zero otherwise (e.g., if the address in @var{child_addr} is outside
the limits of the debuggee's code segment.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node write_sel_addr, writev, write_child, Alphabetical List
@unnumberedsec write_sel_addr
@c From file ./debug.txh
@findex write_sel_addr

@subheading Syntax

@example
#include <debug/dbgcom.h>

int write_sel_addr (unsigned sel, unsigned offset,
                    void *buf, unsigned len);
@end example

@subheading Description

This function transfers @var{len} bytes from the buffer pointed to by
@var{buf} in the data segment whose selector is @var{sel}, at offset
@var{offset}.  The companion function @code{read_sel_addr}
(@pxref{read_sel_addr}) is usually called before @code{write_sel_addr}
to save the original contents, if needed.

@subheading Return Value

The function return zero if it has successfully transferred the data,
non-zero otherwise (e.g., if the address in @var{offset} is outside
the limits of the @var{sel}s segment).

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@c -----------------------------------------------------------------------------
@node writev, xfree, write_sel_addr, Alphabetical List
@unnumberedsec writev
@c From file ./posix/sys/uio/writev.txh
@findex writev

@subheading Syntax

@example
#include <sys/uio.h>

ssize_t writev(int fd, const struct iovec *iov, int iovcnt);
@end example

@subheading Description

@code{writev} performs a scatter-gather write to the specified file
descriptor @var{fd}.  A group of buffers described by the array @var{iov},
with @var{iovcnt} entries, is written to @var{fd} in a similar
way to @code{write} (@pxref{write, , write, libc}).

@code{struct iovec} is defined as follows:

@example
struct iovec @{
  void   *iov_base; /* Base address of a memory region for I/O */
  size_t  iov_len;  /* Size of memory region                   */
@};
@end example

@subheading Return Value

On successful completion the function returns the number of bytes written.
Otherwise, a value of -1 is returned and @code{errno} is set appropriately.

@table @samp

@item EINVAL
One of the following conditions is true:

@itemize @bullet
@item
The total length to write would overflow a @code{ssize_t}.
@item
@var{iovcnt} was negative, zero or larger than @code{IOV_MAX}.
@end itemize

@end table

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab 1003.1-2001; 1003.1-2008; not 1003.2-1992
@end multitable

@c -----------------------------------------------------------------------------
@node xfree, xmalloc, writev, Alphabetical List
@unnumberedsec xfree
@c From file ./compat/stdlib/xfree.txh
@findex xfree
@subheading Syntax

@example
#include <stdlib.h>

void xfree(void *ptr);
@end example

@subheading Description

Frees memory allocated by @code{xmalloc} (@pxref{xmalloc}).  This
function guarantees that a NULL pointer is handled gracefully.

Note that, currently, the header @file{stdlib.h} does @strong{not}
declare a prototype for @code{xfree}, because many programs declare
its prototype in different and conflicting ways.  If you use
@code{xfree} in your own code, you might need to provide your own
prototype explicitly.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
void *f = xmalloc(100);
xfree(f);
@end example

@c -----------------------------------------------------------------------------
@node xmalloc, xrealloc, xfree, Alphabetical List
@unnumberedsec xmalloc
@c From file ./compat/stdlib/xmalloc.txh
@findex xmalloc
@subheading Syntax

@example
#include <stdlib.h>

void *xmalloc(size_t size);
@end example

@subheading Description

This function is just like @code{malloc} (@pxref{malloc}), except that if
there is no more memory, it prints an error message and exits.

Note that, currently, the header @file{stdlib.h} does @strong{not}
declare a prototype for @code{xmalloc}, because many programs declare
its prototype in different and conflicting ways.  If you use
@code{xmalloc} in your own code, you might need to provide your own
prototype explicitly.

@subheading Return Value

A pointer to the newly allocated memory.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char *f = xmalloc(100);
@end example

@c -----------------------------------------------------------------------------
@node xrealloc, , xmalloc, Alphabetical List
@unnumberedsec xrealloc
@c From file ./compat/stdlib/xrealloc.txh
@findex xrealloc
@subheading Syntax

@example
#include <stdlib.h>

void *xrealloc(void *ptr, size_t size);
@end example

@subheading Description

This function is just like @code{realloc} (@pxref{realloc}), except that
if there is no more memory, it prints an error message and exits.  It
can also properly handle @var{ptr} being @code{NULL}. 

Note that, currently, the header @file{stdlib.h} does @strong{not}
declare a prototype for @code{xrealloc}, because many programs declare
its prototype in different and conflicting ways.  If you use
@code{xrealloc} in your own code, you might need to provide your own
prototype explicitly.

@subheading Return Value

A pointer to a possibly new block.

@subheading Portability

@multitable {ANSI/ISO C} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item ANSI/ISO C
@tab No
@item POSIX
@tab No
@end multitable


@subheading Example

@example
char *buf;
buf = (char *)xrealloc(buf, new_size);
@end example
