This is ../../info/libc.info, produced by makeinfo version 4.9 from
libc.tex.

This is the reference manual for libc.a

Copyright (c) 1996 DJ Delorie


File: libc.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

* Menu:

* Introduction::

* Functional Categories::  All public symbols listed by
                           category

* Alphabetical List::      All public symbols in alphabetical
                           order

* Unimplemented::          Compatibility functions that either
                           always fail or do nothing

* Function Index::
* Variable Index::
* Data Type Index::
* Concept Index::


File: libc.info,  Node: Introduction,  Next: Functional Categories,  Prev: Top,  Up: Top

1 Introduction
**************

The standard C library, `libc.a', is automatically linked into your
programs by the `gcc' control program.  It provides many of the
functions that are normally associated with C programs.  This document
gives the proper usage information about each of the functions and
variables found in `libc.a'.

For each function or variable that the library provides, the definition
of that symbol will include information on which header files to include
in your source to obtain prototypes and type definitions relevant to the
use of that symbol.

Note that many of the functions in `libm.a' (the math library) are
defined in `math.h' but are not present in libc.a.  Some are, which may
get confusing, but the rule of thumb is this--the C library contains
those functions that ANSI dictates must exist, so that you don't need
the `-lm' if you only use ANSI functions.  In contrast, `libm.a'
contains more functions and supports additional functionality such as
the `matherr' call-back and compliance to several alternative standards
of behavior in case of FP errors.  *Note libm::, for more details.

Debugging support functions are in the library `libdbg.a'; link your
program with `-ldbg' to use them.


File: libc.info,  Node: Functional Categories,  Next: Alphabetical List,  Prev: Introduction,  Up: Top

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::


File: libc.info,  Node: bios functions,  Next: conio functions,  Up: Functional Categories

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::


File: libc.info,  Node: conio functions,  Next: cpu functions,  Prev: bios functions,  Up: Functional Categories

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::


File: libc.info,  Node: cpu functions,  Next: ctype functions,  Prev: conio functions,  Up: Functional Categories

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::


File: libc.info,  Node: ctype functions,  Next: debugging functions,  Prev: cpu functions,  Up: Functional Categories

ctype functions
===============

* Menu:

* isalnum::
* isalpha::
* isascii::
* isblank::
* iscntrl::
* isdigit::
* isgraph::
* islower::
* isprint::
* ispunct::
* isspace::
* isupper::
* isxdigit::
* toascii::
* _tolower::
* tolower::
* _toupper::
* toupper::


File: libc.info,  Node: debugging functions,  Next: dos functions,  Prev: ctype functions,  Up: Functional Categories

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::


File: libc.info,  Node: dos functions,  Next: dpmi functions,  Prev: debugging functions,  Up: Functional Categories

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::


File: libc.info,  Node: dpmi functions,  Next: environment functions,  Prev: dos functions,  Up: Functional Categories

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::


File: libc.info,  Node: environment functions,  Next: file system functions,  Prev: dpmi functions,  Up: Functional Categories

environment functions
=====================

* Menu:

* getenv::
* putenv::
* setenv::
* unsetenv::


File: libc.info,  Node: file system functions,  Next: go32 functions,  Prev: environment functions,  Up: Functional Categories

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::


File: libc.info,  Node: go32 functions,  Next: io functions,  Prev: file system functions,  Up: Functional Categories

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::


File: libc.info,  Node: io functions,  Next: locale functions,  Prev: go32 functions,  Up: Functional Categories

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::


File: libc.info,  Node: locale functions,  Next: math functions,  Prev: io functions,  Up: Functional Categories

locale functions
================

* Menu:

* localeconv::
* mblen::
* mbstowcs::
* mbtowc::
* setlocale::
* strcoll::
* strxfrm::
* wcstombs::
* wctomb::


File: libc.info,  Node: math functions,  Next: memory functions,  Prev: locale functions,  Up: Functional Categories

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::


File: libc.info,  Node: memory functions,  Next: misc functions,  Prev: math functions,  Up: Functional Categories

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::


File: libc.info,  Node: misc functions,  Next: mono functions,  Prev: memory functions,  Up: Functional Categories

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::


File: libc.info,  Node: mono functions,  Next: posix functions,  Prev: misc functions,  Up: Functional Categories

mono functions
==============

* Menu:

* _mono_clear::
* _mono_printf::
* _mono_putc::


File: libc.info,  Node: posix functions,  Next: process functions,  Prev: mono functions,  Up: Functional Categories

posix functions
===============

* Menu:

* confstr::
* ctermid::
* getdtablesize::
* pathconf::
* sysconf::


File: libc.info,  Node: process functions,  Next: profiling functions,  Prev: posix functions,  Up: Functional Categories

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::


File: libc.info,  Node: profiling functions,  Next: random number functions,  Prev: process functions,  Up: Functional Categories

profiling functions
===================

* Menu:

* moncontrol::
* monstartup::


File: libc.info,  Node: random number functions,  Next: search functions,  Prev: profiling functions,  Up: Functional Categories

random number functions
=======================

* Menu:

* initstate::
* rand::
* rand48::
* random::
* setstate::
* srand::
* srandom::


File: libc.info,  Node: search functions,  Next: shell functions,  Prev: random number functions,  Up: Functional Categories

search functions
================

* Menu:

* hcreate::
* hdestroy::
* hsearch::


File: libc.info,  Node: shell functions,  Next: signal functions,  Prev: search functions,  Up: Functional Categories

shell functions
===============

* Menu:

* glob::
* globfree::


File: libc.info,  Node: signal functions,  Next: sound functions,  Prev: shell functions,  Up: Functional Categories

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::


File: libc.info,  Node: sound functions,  Next: startup functions,  Prev: signal functions,  Up: Functional Categories

sound functions
===============

* Menu:

* nosound::
* sound::


File: libc.info,  Node: startup functions,  Next: stdio functions,  Prev: sound functions,  Up: Functional Categories

startup functions
=================

* Menu:

* __crt0_glob_function::
* __crt0_load_environment_file::
* __crt0_setup_arguments::
* _crt0_startup_flags::
* _stklen::


File: libc.info,  Node: stdio functions,  Next: string functions,  Prev: startup functions,  Up: Functional Categories

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::


File: libc.info,  Node: string functions,  Next: sys functions,  Prev: stdio functions,  Up: Functional Categories

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::


File: libc.info,  Node: sys functions,  Next: termios functions,  Prev: string functions,  Up: Functional Categories

sys functions
=============

* Menu:

* flock::


File: libc.info,  Node: termios functions,  Next: time functions,  Prev: sys functions,  Up: Functional Categories

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::


File: libc.info,  Node: time functions,  Next: unistd functions,  Prev: termios functions,  Up: Functional Categories

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::


File: libc.info,  Node: unistd functions,  Next: unix functions,  Prev: time functions,  Up: Functional Categories

unistd functions
================

* Menu:

* llockf::
* lockf::


File: libc.info,  Node: unix functions,  Prev: unistd functions,  Up: Functional Categories

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::


File: libc.info,  Node: Alphabetical List,  Next: Unimplemented,  Prev: Functional Categories,  Up: Top

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::


File: libc.info,  Node: _8087,  Next: a64l,  Up: Alphabetical List

_8087
=====

Syntax
------

     #include <dos.h>

     extern int _8087;

Description
-----------

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

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: a64l,  Next: abort,  Prev: _8087,  Up: Alphabetical List

a64l
====

Syntax
------

     #include <stdlib.h>

     long a64l(const char *string);

Description
-----------

This function takes a pointer to a radix-64 representation, with the
first digit the least significant, and returns the corresponding `long'
value.

If STRING contains more than six characters, only the first six are
used.  If the first six characters of STRING contain a null terminator,
only those characters before the null terminator are used.  `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 `l64a' function (*note l64a::).

Return Value
------------

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

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)

Notes:

  1. This function is new to the Posix 1003.1-200x draft


File: libc.info,  Node: abort,  Next: abs,  Prev: a64l,  Up: Alphabetical List

abort
=====

Syntax
------

     #include <stdlib.h>

     void abort(void);

Description
-----------

When you call `abort', the message "Abort!" is printed on stdout and
the program is aborted by calling `raise (SIGABRT)' (*note SIGABRT:
signal.).  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 `SIGABRT' signal is caught by a handler that
returns, the program exits with an exit code of 1.

Return Value
------------

This function does not return.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     if ((q = malloc(100)) == NULL)
       abort();


File: libc.info,  Node: abs,  Next: access,  Prev: abort,  Up: Alphabetical List

abs
===

Syntax
------

     #include <stdlib.h>

     int abs(int value);

Return Value
------------

The absolute value of `value' is returned.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     int sq = 7;
     sq = sq * abs(sq) + 1;


File: libc.info,  Node: access,  Next: acos,  Prev: abs,  Up: Alphabetical List

access
======

Syntax
------

     #include <unistd.h>

     int access(const char *filename, int flags);

Description
-----------

This function determines what kind of access modes a given file allows.
The parameter FLAGS is the logical `or' of one or more of the following
flags:

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

`W_OK'
     Request if the file is writable.

`X_OK'
     Request if the file is executable.

`F_OK'
     Request if the file exists.

`D_OK'
     Request if the file is really a directory.


Return Value
------------

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

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

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


File: libc.info,  Node: acos,  Next: acosh,  Prev: access,  Up: Alphabetical List

acos
====

Syntax
------

     #include <math.h>

     double acos(double x);

Description
-----------

This function returns the angle in the range `[0..Pi]' radians whose
cosine is X.  If the absolute value of X is greater than 1, a domain
error occurs, and `errno' is set to `EDOM'.

Return Value
------------

The arc cosine, in radians, of X.  If the absolute value of X is
greater than 1, the function returns a `NaN'.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: acosh,  Next: addmntent,  Prev: acos,  Up: Alphabetical List

acosh
=====

Syntax
------

     #include <math.h>

     double acosh(double x);

Description
-----------

This function returns the inverse hyperbolic cosine of X.

Return Value
------------

The inverse hyperbolic cosine of X.  If the value of X is less than 1,
the return value is `NaN' and `errno' is set to `EDOM'.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: addmntent,  Next: alarm,  Prev: acosh,  Up: Alphabetical List

addmntent
=========

Syntax
------

     #include <mntent.h>

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

Description
-----------

This function is a no-op for MS-DOS, but is provided to assist in Unix
ports.  *Note getmntent::.

Return Value
------------

This function always returns nonzero to signify an error.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: alarm,  Next: alloca,  Prev: addmntent,  Up: Alphabetical List

alarm
=====

Syntax
------

     #include <unistd.h>

     unsigned alarm(unsigned seconds);

Description
-----------

This function causes the signal `SIGALRM' to be raised in SECONDS
seconds.  A value of zero for 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 *Note
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 `Background: Always suspend' property in the Property
Sheets.  Therefore, `alarm' will not work in background programs on
Windows 9X.

Return Value
------------

The number of seconds remaining on the timer (i.e. always SECONDS).

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     signal(SIGALRM,my_alarm_routine);
     alarm(5);


File: libc.info,  Node: alloca,  Next: asctime,  Prev: alarm,  Up: Alphabetical List

alloca
======

Syntax
------

     #include <stdlib.h>

     void *alloca(size_t _size)

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.

Return Value
------------

A pointer to the memory, else NULL.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

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


File: libc.info,  Node: asctime,  Next: asctime_r,  Prev: alloca,  Up: Alphabetical List

asctime
=======

Syntax
------

     #include <time.h>

     char *asctime(const struct tm *tptr);

Description
-----------

This function returns a string representing the time from TPTR.  The
string returned is always 26 characters and has this format:

     Sun Jan 01 12:34:56 1993\n\0

The string pointed to is in a static buffer and will be overwritten with
each call to `asctime'.  The string should be copied if it needs to be
preserved.  *Note asctime_r::, for an alternate interface that allows
the caller to provide a buffer to store the string.

*Note gmtime::, for a description of type `struct tm'.

Return Value
------------

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

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

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


File: libc.info,  Node: asctime_r,  Next: asin,  Prev: asctime,  Up: Alphabetical List

asctime_r
=========

Syntax
------

     #include <time.h>

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

Description
-----------

This function returns a string representing the time from TPTR.  The
string returned is always 26 characters and has this format:

     Sun Jan 01 12:34:56 1993\n\0

*Note asctime::, for an alternate ISO Standard interface.

*Note gmtime::, for a description of type `struct tm'.

Return Value
------------

A pointer to BUF containing the character representation of the time.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

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));


File: libc.info,  Node: asin,  Next: asinh,  Prev: asctime_r,  Up: Alphabetical List

asin
====

Syntax
------

     #include <math.h>

     double asin(double x);

Description
-----------

This function returns the angle in the range `[-Pi/2..Pi/2]' whose sine
is X.

Return Value
------------

The inverse sine, in radians, of X.  If the absolute value of X is
greater than 1, the return value is `NaN' and `errno' is set to `EDOM'.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: asinh,  Next: asnprintf,  Prev: asin,  Up: Alphabetical List

asinh
=====

Syntax
------

     #include <math.h>

     double asinh(double x);

Description
-----------

This function returns the inverse hyperbolic sine of the argument X.

Return Value
------------

The inverse hyperbolic sine of X.  If the argument X is a `NaN', the
return value is `NaN' and `errno' is set to `EDOM'.  If X is a positive
or negative `Inf', the return value is equal to the value of X, and
`errno' is left unchanged.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: asnprintf,  Next: asprintf,  Prev: asinh,  Up: Alphabetical List

asnprintf
=========

Syntax
------

     #include <stdio.h>

     char *asnprintf(char *buffer, size_t *np, const char *format, ...);

Description
-----------

Sends formatted output from the arguments (...) 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 BUFFER.
The buffer length must be passed by NP.  The function will write up to
*NP - 1 characters.  The *NPth character is used for the terminating
nul.  Upon error, `errno' is set and a `NULL' pointer is returned.

If BUFFER is a `NULL' pointer or *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 NP pointer.  The allocated memory must
be returned to the heap with `free' (*note free::).

Return Value
------------

If dynamic allocation occurs, a pointer to the newly allocated string
buffer is returned else BUFFER.  The number of characters that would
have been written (excluding the trailing nul) is returned by NP;
otherwise the function returns a `NULL' pointer.

The maximum accepted value of *NP is `INT_MAX'.  `INT_MAX' is defined
in `<limits.h>'.  A `NULL' pointer is returned and `errno' is set to
`EFBIG', if *NP is greater than this limit.

Portability
-----------

ANSI/ISO C   No (see note 1)
POSIX        No

Notes:

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


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.  */
     }


File: libc.info,  Node: asprintf,  Next: assert,  Prev: asnprintf,  Up: Alphabetical List

asprintf
========

Syntax
------

     #include <stdio.h>

     int asprintf(char **bufferp, const char *format, ...);

Description
-----------

Sends formatted output from the arguments (...) including the
terminating null byte to the allocated buffer and returns a pointer to
it via the first parameter *BUFFERP.  This memory must be returned to
the heap with `free' (*note free::).  This function is analog of
`sprintf()' (*note sprintf::).

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 *BUFFERP is set to
`NULL'.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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.  */
     }


File: libc.info,  Node: assert,  Next: atan,  Prev: asprintf,  Up: Alphabetical List

assert
======

Syntax
------

     #define NDEBUG
     #include <assert.h>

     assert(expression);
     assertval(expression);

Description
-----------

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

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

Return Value
------------

`assert' returns 1 if its argument is non-zero, else it aborts.

`assertval' returns the value of its EXPRESSION argument, if non-zero,
else it aborts.

Portability
-----------

ANSI/ISO C   C89; C99; (see note 1)
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 2)

Notes:

  1. `assert' is ANSI, `assertval' is not.

  2. `assert' is Posix, `assertval' is not.

Example
-------

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


File: libc.info,  Node: atan,  Next: atan2,  Prev: assert,  Up: Alphabetical List

atan
====

Syntax
------

     #include <math.h>

     double atan(double x);

Description
-----------

This function computes the angle, in the range `[-Pi/2..Pi/2]' radians,
whose tangent is X.

Return Value
------------

The arc tangent, in radians, of X.  If X is a `NaN', the return value
is `NaN' and `errno' is set to `EDOM'.  If X is a positive or negative
`Inf', the return value is equal to positive or negative `Pi/2',
respectively, and `errno' is left unchanged.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: atan2,  Next: atanh,  Prev: atan,  Up: Alphabetical List

atan2
=====

Syntax
------

     #include <math.h>

     double atan2(double y, double x);

Description
-----------

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

Return Value
------------

The arc tangent, in radians, of `Y/X'.  `Pi' is returned if X is
negative and Y is a negative zero, `-0.0'.  `-Pi' is returned, if X is
negative, and Y is a positive zero, `+0.0'.

If either X or Y is infinite, `atan2' returns, respectively, `Pi' with
the sign of Y or zero, and `errno' is left unchanged.  However, if
_both_ arguments are infinite, the return value is `NaN' and `errno' is
set to `EDOM'.

A `NaN' is returned, and `errno' is set to `EDOM', if either X and Y
are both zero, or if either one of the arguments is a `NaN'.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: atanh,  Next: atexit,  Prev: atan2,  Up: Alphabetical List

atanh
=====

Syntax
------

     #include <math.h>

     double atanh(double x);

Description
-----------

This function computes the inverse hyperbolic tangent of X.

Return Value
------------

The inverse hyperbolic tangent of X.  If the the value of X is plus or
minus 1, the return value is an `Inf' with the same sign as the
argument X, and `errno' is set to `ERANGE'.  If the absolute value of X
is greater than 1, the return value is `NaN' and `errno' is set to
`EDOM'.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: atexit,  Next: atof,  Prev: atanh,  Up: Alphabetical List

atexit
======

Syntax
------

     #include <stdlib.h>

     int atexit(void (*func)(void));

Description
-----------

This function places the specified function FUNC on a list of functions
to be called when `exit' is called.  These functions are called as if a
last-in-first-out queue is used, that is, the last function registered
with `atexit' will be the first function called by `exit'.

At least 32 functions can be registered this way.

Return Value
------------

Zero on success, non-zero on error.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

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

     ...
     atexit(exit_func);
     ...


File: libc.info,  Node: atof,  Next: atoi,  Prev: atexit,  Up: Alphabetical List

atof
====

Syntax
------

     #include <stdlib.h>

     double atof(const char *string);

Description
-----------

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

This function is almost like `strtod(string, NULL)' (*note strtod::).

Return Value
------------

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

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     main(int argc, char **argv)
     {
       double d = atof(argv[1]);
       ...


File: libc.info,  Node: atoi,  Next: atol,  Prev: atof,  Up: Alphabetical List

atoi
====

Syntax
------

     #include <stdlib.h>

     int atoi(const char *string);

Description
-----------

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

This function is almost like `(int)strtol(string, NULL, 10)' (*note
strtol::).

Return Value
------------

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

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     main(int argc, char **argv)
     {
       int i = atoi(argv[1]);
       ...


File: libc.info,  Node: atol,  Next: _atold,  Prev: atoi,  Up: Alphabetical List

atol
====

Syntax
------

     #include <stdlib.h>

     long atol(const char *string);

Description
-----------

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

This function is almost like `strtol(string, NULL, 10)' (*note
strtol::).

Return Value
------------

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

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     main(int argc, char **argv)
     {
       long l = atol(argv[1]);
       ...


File: libc.info,  Node: _atold,  Next: atoll,  Prev: atol,  Up: Alphabetical List

_atold
======

Syntax
------

     #include <stdlib.h>

     long double _atold(const char *string);

Description
-----------

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

This function is almost like `_strtold(string, NULL)' (*note
_strtold::).

Return Value
------------

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

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     main(int argc, char **argv)
     {
       long double d = _atold(argv[1]);
       ...


File: libc.info,  Node: atoll,  Next: basename,  Prev: _atold,  Up: Alphabetical List

atoll
=====

Syntax
------

     #include <stdlib.h>

     long long int atoll(const char *string);

Description
-----------

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

This function is almost like `strtoll(string, NULL, 10)' (*note
strtoll::).

Return Value
------------

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

Portability
-----------

ANSI/ISO C   C99; not C89
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992

Example
-------

     main(int argc, char **argv)
     {
       long long int l = atoll(argv[1]);
       ...
     }


File: libc.info,  Node: basename,  Next: bcmp,  Prev: atoll,  Up: Alphabetical List

basename
========

Syntax
------

     #include <unistd.h>

     char * basename (const char *fname);

Description
-----------

This function returns the "basename" of the file, which is the last
part of its full name given by FNAME, with the drive letter and leading
directories stripped off.  For example, the basename of
`c:/foo/bar/file.ext' is `file.ext', and the basename of `a:foo' is
`foo'.  Trailing slashes and backslashes are significant: the basename
of `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.

Return Value
------------

A pointer into the original file name where the basename starts.  Note
that this is *not* a new buffer allocated with `malloc'.  If FNAME is a
NULL pointer, the function will return a NULL pointer.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

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


File: libc.info,  Node: bcmp,  Next: bcopy,  Prev: basename,  Up: Alphabetical List

bcmp
====

Syntax
------

     #include <string.h>

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

Description
-----------

Compare memory pointed to by PTR1 and PTR2 for at most LENGTH bytes.

Return Value
------------

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

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);
     }


File: libc.info,  Node: bcopy,  Next: bdos,  Prev: bcmp,  Up: Alphabetical List

bcopy
=====

Syntax
------

     #include <string.h>

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

Description
-----------

Copy LENGTH bytes from SOURCE to DEST.  Overlapping regions are handled
properly, although this behavior is not portable.

Return Value
------------

No value is returned.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     struct s a, b;
     bcopy(a, b, sizeof(struct s));


File: libc.info,  Node: bdos,  Next: bdosptr,  Prev: bcopy,  Up: Alphabetical List

bdos
====

Syntax
------

     #include <dos.h>

     int bdos(int func, unsigned dx, unsigned al);

Description
-----------

Calls function FUNC of the software interrupt 0x21, passing it AL as
the subfunction and (the lower 16 bit of) DX in the `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 `AL'
and `DX' registers only.  For functions which require a pointer in the
`DX' register, use `bdosptr' (*note bdosptr::).

Return Value
------------

Whatever the called function returns in the AX register.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

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


File: libc.info,  Node: bdosptr,  Next: _bios_disk,  Prev: bdos,  Up: Alphabetical List

bdosptr
=======

Syntax
------

     #include <dos.h>

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

Description
-----------

Calls function FUNC of the software interrupt 0x21, passing it AL as
the subfunction and a pointer to a copy of the buffer contents whose
address is in PTR through the `DX' register.  This function will only
work for a subset of DOS which require an argument in the `AL' register
and a pointer in `DX' register.  For functions which require
non-pointer arguments in the `DX' register, use `bdos' (*note bdos::).
To make the contents of PTR available to DOS, `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
`DX' are _NOT_ supported (notably, most of the FCB-based functions).
*Note int86::, for the list of supported functions.

Return Value
------------

Whatever the called function returns in the AX register.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

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


File: libc.info,  Node: _bios_disk,  Next: _bios_equiplist,  Prev: bdosptr,  Up: Alphabetical List

_bios_disk
==========

Syntax
------

     #include <bios.h>

     unsigned _bios_disk(unsigned cmd, struct diskinfo_t *di)

Description
-----------

This function interfaces with the BIOS disk service (interrupt 0x13).
The parameter CMD select the corresponding disk service and the
structure DI holds the disk parameters.

     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. */
     }

The following services are available based on value of CMD:

`_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 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.

`_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.

`_DISK_READ'
     Reads one or more disk sectors into memory. 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 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.

`_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.

`_DISK_FORMAT'
     Formats the track specified by DISKINFO. The HEAD and TRACK fields
     indicate the track to format. Only one track can be formatted in a
     single call. The 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.

`_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 BUFFER) 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 compared in the
     low-order byte (AL), as defined below under Return Value.


Return Value
------------

Return value of AX register. The meaning of high-order byte (AH):
     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

Portability
-----------

ANSI/ISO C   No
POSIX        No

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.");


File: libc.info,  Node: _bios_equiplist,  Next: _bios_keybrd,  Prev: _bios_disk,  Up: Alphabetical List

_bios_equiplist
===============

Syntax
------

     #include <bios.h>

     unsigned _bios_equiplist(void)

Description
-----------

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

     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

Return Value
------------

The equipment word.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     if ( _bios_equiplist() & 0xc000 )
       do_printing();


File: libc.info,  Node: _bios_keybrd,  Next: _bios_memsize,  Prev: _bios_equiplist,  Up: Alphabetical List

_bios_keybrd
============

Syntax
------

     #include <bios.h>

     unsigned _bios_keybrd(unsigned cmd);

Description
-----------

The `_bios_keybrd' function uses INT 0x16 to access the keyboard
services.  The CMD argument can be any of the following manifest
constants:

`_KEYBRD_READ'
     read the next key pressed.

`_NKEYBRD_READ'
     read the next extended key pressed.  Unlike `_KEYBRD_READ', this
     command knows about keys introduced with the AT-style 101-key
     keyboards, such as <F11> and <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 `E0h' (224 decimal)
     prefix, so code that uses `_NKEYBRD_READ' should deal with this
     complexity.

`_KEYBRD_READY'
     check if a key is waiting in the keyboard buffer.

`_NKEYBRD_READY'
     check if an extended key is waiting in the keyboard buffer.  Like
     `_KEYBRD_READY', but recognizes extended keys such as <F12>, which
     `_KEYBRD_READY' ignores.

`_KEYBRD_SHIFTSTATUS'
     read keyboard shift state (the byte at the address `40h:17h' in the
     BIOS data area):

          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

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

          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


Return Value

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

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

With the `*_READ' and `*_READY' arguments, the `_bios_keybrd' function
returns -1 if `Ctrl+<BREAK>' has been pressed and is the next keystroke
to be read.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     while( !_bios_keybrd(_KEYBRD_READY) )
       try_to_do_something();


File: libc.info,  Node: _bios_memsize,  Next: _bios_printer,  Prev: _bios_keybrd,  Up: Alphabetical List

_bios_memsize
=============

Syntax
------

     #include <bios.h>

     unsigned _bios_memsize(void);

Description
-----------

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

Return Value
------------

Size of memory (in K).

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     printf("This system has %d bytes of memory\n", _bios_memsize() * 1024);


File: libc.info,  Node: _bios_printer,  Next: _bios_serialcom,  Prev: _bios_memsize,  Up: Alphabetical List

_bios_printer
=============

Syntax
------

     #include <bios.h>

     unsigned _bios_printer(unsigned cmd, unsigned printer, unsigned data);

Description
-----------

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

`_PRINTER_INIT'

`Reset and initialize the specified printer port'

`_PRINTER_STATUS'
     Return the status of the specified printer port

`_PRINTER_WRITE'
     Print the DATA argument to the specified printer port


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:

     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

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     while (*c)
       _bios_printer(_PRINTER_WRITE, *c++, 0);


File: libc.info,  Node: _bios_serialcom,  Next: _bios_timeofday,  Prev: _bios_printer,  Up: Alphabetical List

_bios_serialcom
===============

Syntax
------

     #include <bios.h>

     unsigned _bios_serialcom(unsigned cmd, unsigned serialport,
                              unsigned data);

Description
-----------

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

`_COM_INIT'
     Initialize com port (DATA is the settings)

`_COM_RECEIVE'
     Read a byte from port

`_COM_SEND'
     Write a byte to port

`_COM_STATUS'
     Get the port status


The DATA argument is ignored if CMD is set to _COM_RECEIVE or
_COM_STATUS. The DATA argument for _COM_INIT is created by combining
one or more of the following constants (with the OR operator):

     _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

The default value of DATA is 1 stop bit, no parity, and 110 baud.

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
CMD value. The high-order bits are as follows:

     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

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:

     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

Portability
-----------

ANSI/ISO C   No
POSIX        No

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]);


File: libc.info,  Node: _bios_timeofday,  Next: bioscom,  Prev: _bios_serialcom,  Up: Alphabetical List

_bios_timeofday
===============

Syntax
------

     #include <bios.h>

     unsigned _bios_timeofday(unsigned cmd, unsigned long *timeval);

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 CMD argument
can be either the _TIME_GETCLOCK or _TIME_SETCLOCK manifest constant.

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.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: bioscom,  Next: biosdisk,  Prev: _bios_timeofday,  Up: Alphabetical List

bioscom
=======

Syntax
------

     #include <bios.h>

     int bioscom(int cmd, char data, int port);

Description
-----------

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

The valid values of cmd are:

0 - initialize com port (DATA is the settings)

1 - write byte to port

2 - read byte from port (DATA is ignored)

3 - get port status

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

     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

For writing a character out to the port, the return value's lower 8
bits contain the same byte as passed as the DATA argument.

For reading a character from the port, the value of 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.

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.

     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)

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

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


File: libc.info,  Node: biosdisk,  Next: biosequip,  Prev: bioscom,  Up: Alphabetical List

biosdisk
========

Syntax
------

     #include <bios.h>

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

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:

0 - reset disk subsystem

1 - get status of last operation (see *Note _bios_disk::, for possible values)

2 - read one or more sectors

3 - write one or more sectors

5 - format a track

6 - format a cylinder and set bad sector flag

7 - format drive from specified cylinder

8 - get drive parameters

9 - initialize drive parameters

10 - read long sectors

11 - write long sectors

12 - seek to cylinder

13 - alternate fixed disk reset

14 - read sector buffer

15 - write sector buffer

16 - test for drive ready

17 - recalibrate drive

18 - controller RAM diagnostic

19 - controller drive diagnostic

20 - controller internal diagnostic

21 - get DASD type

22 - read disk change line status

23 - set DASD type (pass DASD code in NSECTS)

24 - set media type for format

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 BUFFER as follows:

byte 0 = sectors per track (bits 0..5), top two bits of cylinder (in bits 6..7)

byte 1 = cylinders (bits 0..7)

byte 2 = number of drives

byte 3 = number of heads

Return Value
------------

The value of AH returned by the BIOS.  See *Note _bios_disk::, for a
detailed list of possible status and error codes.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

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


File: libc.info,  Node: biosequip,  Next: bioskey,  Prev: biosdisk,  Up: Alphabetical List

biosequip
=========

Syntax
------

     #include <bios.h>

     int biosequip(void);

Description
-----------

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

     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)

Return Value
------------

The equipment word.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     if (biosequip() & 0xc000)
       do_printing();


File: libc.info,  Node: bioskey,  Next: biosmemory,  Prev: biosequip,  Up: Alphabetical List

bioskey
=======

Syntax
------

     #include <bios.h>

     int bioskey(int command)

Description
-----------

This function issues the BIOS keyboard interrupt 16h with COMMAND in
the AH register, and returns the results of that call.  The argument
COMMAND can accept the following values:

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.

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 `Ctrl-<BREAK>' key was pressed, returns -1.

COMMAND = 02h
     Returns the keyboard shift state:

          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

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

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

COMMAND = 11h
     Like the case of COMMAND = 1, but recognizes the additional keys
     of the extended keyboard.

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:

          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


Return Value
------------

Depends on COMMAND.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     while (!bioskey(1))
       do_stuff();


File: libc.info,  Node: biosmemory,  Next: biosprint,  Prev: bioskey,  Up: Alphabetical List

biosmemory
==========

Syntax
------

     #include <bios.h>

     unsigned biosmemory(void);

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.

Return Value
------------

Bytes of memory / 1024.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

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


File: libc.info,  Node: biosprint,  Next: biostime,  Prev: biosmemory,  Up: Alphabetical List

biosprint
=========

Syntax
------

     #include <bios.h>

     int biosprint(int cmd, int byte, int port)

Description
-----------

COMMAND = 0
     `byte' is sent to parallel port PORT.

COMMAND = 1
     Parallel port PORT is reset and initialized.

COMMAND = 2
     The status of parallel port PORT is returned.

          7654 3210  Meaning

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


Return Value
------------

The printer status.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     while (*c)
       biosprint(0, *c++, 0);


File: libc.info,  Node: biostime,  Next: blinkvideo,  Prev: biosprint,  Up: Alphabetical List

biostime
========

Syntax
------

     #include <bios.h>

     long biostime(int cmd, long newtime);

Description
-----------

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

Return Value
------------

When reading, the number of ticks since midnight.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     long ticks = biostime(0, 0);


File: libc.info,  Node: blinkvideo,  Next: brk,  Prev: biostime,  Up: Alphabetical List

blinkvideo
==========

Syntax
------

     #include <conio.h>

     void blinkvideo(void);

Description
-----------

Bit 7 (`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 `intensevideo' (*note
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 `0040h:0065h' in the BIOS area indicates
the current state: if it's 1 (the default), blinking characters will be
displayed.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: brk,  Next: bsearch,  Prev: blinkvideo,  Up: Alphabetical List

brk
===

Syntax
------

     #include <unistd.h>

     int brk(void *ptr);

Description
-----------

This function changes the _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 PTR.  Normally,
this is done transparently through the `malloc' function.

Return Value
------------

Zero if the break was changed, -1 if not.  `errno' is set to the error.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

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


File: libc.info,  Node: bsearch,  Next: bzero,  Prev: brk,  Up: Alphabetical List

bsearch
=======

Syntax
------

     #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));

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 PTF and passing it the key as CKEY and a
pointer to one of the elements of the array as 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 BASE and contains NUM elements, each of
size SIZE.

Return Value
------------

Returns a pointer to the element that matches the key, else NULL.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     typedef struct {
       int a, b;
     } q;

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

     q qlist[100];

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


File: libc.info,  Node: bzero,  Next: calloc,  Prev: bsearch,  Up: Alphabetical List

bzero
=====

Syntax
------

     #include <string.h>

     void bzero(void *pointer, int length);

Description
-----------

The data at POINTER is filled with LENGTH zeros.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     char foo[100];
     bzero(foo,100);


File: libc.info,  Node: calloc,  Next: cbrt,  Prev: bzero,  Up: Alphabetical List

calloc
======

Syntax
------

     #include <stdlib.h>

     void *calloc(size_t num_elements, size_t size);

Description
-----------

This function allocates enough memory for NUM_ELEMENTS objects of size
SIZE.  The memory returned is initialized to all zeros.  The pointer
returned should later be passed to free (*note free::) so that the
memory can be returned to the heap.

You may use cfree (*note cfree::) to free the pointer also; it just
calls free.

Return Value
------------

A pointer to the memory, or `NULL' if no more memory is available.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

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


File: libc.info,  Node: cbrt,  Next: ceil,  Prev: calloc,  Up: Alphabetical List

cbrt
====

Syntax
------

     #include <math.h>

     double cbrt(double x);

Description
-----------

This function computes the cube root of X.  It is faster and more
accurate to call `cbrt(X)' than to call `pow(X, 1./3.)'.

Return Value
------------

The cube root of X.  If the value of X is `NaN', the return value is
`NaN' and `errno' is set to `EDOM'.  Infinite arguments are returned
unchanged, without setting `errno'.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: ceil,  Next: cfgetispeed,  Prev: cbrt,  Up: Alphabetical List

ceil
====

Syntax
------

     #include <math.h>

     double ceil(double x);

Description
-----------

This function computes the smallest integer greater than or equal to X.

Return Value
------------

The smallest integer value greater than or equal to X.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: cfgetispeed,  Next: cfgetospeed,  Prev: ceil,  Up: Alphabetical List

cfgetispeed
===========

Syntax
------

     #include <termios.h>

     speed_t cfgetispeed (const struct termios *termiosp);

Description
-----------

This function gets the input line speed stored in the structure
TERMIOSP.  *Note 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.

Return Value
------------

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

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: cfgetospeed,  Next: cfmakeraw,  Prev: cfgetispeed,  Up: Alphabetical List

cfgetospeed
===========

Syntax
------

     #include <termios.h>

     speed_t cfgetospeed (const struct termios *termiosp);

Description
-----------

This function gets the output line speed stored in the structure
TERMIOSP.  *Note 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.

Return Value
------------

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

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: cfmakeraw,  Next: cfree,  Prev: cfgetospeed,  Up: Alphabetical List

cfmakeraw
=========

Syntax
------

     #include <termios.h>

     void cfmakeraw (struct termios *termiosp);

Description
-----------

This function sets the structure specified by TERMIOSP for raw mode.
It is provided for compatibility only.  Note that the termios emulation
handles console only.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: cfree,  Next: cfsetispeed,  Prev: cfmakeraw,  Up: Alphabetical List

cfree
=====

Syntax
------

     #include <stdlib.h>

     void cfree(void *pointer);

Description
-----------

This function returns the memory allocated by calloc (*note calloc::) to
the heap.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

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


File: libc.info,  Node: cfsetispeed,  Next: cfsetospeed,  Prev: cfree,  Up: Alphabetical List

cfsetispeed
===========

Syntax
------

     #include <termios.h>

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

Description
-----------

This function sets the input line speed stored in the structure
TERMIOSP to SPEED.  *Note 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.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: cfsetospeed,  Next: cfsetspeed,  Prev: cfsetispeed,  Up: Alphabetical List

cfsetospeed
===========

Syntax
------

     #include <termios.h>

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

Description
-----------

This function sets the output line speed stored in the structure
TERMIOSP to SPEED.  *Note 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.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: cfsetspeed,  Next: cgets,  Prev: cfsetospeed,  Up: Alphabetical List

cfsetspeed
==========

Syntax
------

     #include <termios.h>

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

Description
-----------

This function sets the input and output line speed stored in the
structure TERMIOSP to SPEED.  It is provided for compatibility only.
Note that the termios emulation handles console only.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: cgets,  Next: chdir,  Prev: cfsetspeed,  Up: Alphabetical List

cgets
=====

Syntax
------

     #include <conio.h>

     char *cgets(char *_str);

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.

Return Value
------------

A pointer to the first character read.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: chdir,  Next: _check_v2_prog,  Prev: cgets,  Up: Alphabetical List

chdir
=====

Syntax
------

     #include <unistd.h>

     int chdir(const char *new_directory);

Description
-----------

This function changes the current directory to 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.

Return Value
------------

Zero if the new directory exists, else nonzero and `errno' set if error.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     if (chdir("/tmp"))
       perror("/tmp");


File: libc.info,  Node: _check_v2_prog,  Next: chmod,  Prev: chdir,  Up: Alphabetical List

_check_v2_prog
==============

Syntax
------

     #include <sys/system.h>

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

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 `NULL' pointer as
`program' (in this case `fd' is ignored), then the file named by
`program' is opened and closed by `_check_v2_prog'.

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

Return Value
------------

`_v2_prog_type' is defined in `sys/system.h' like the following:


     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;

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

*Warning:* Do not modify any of the data in this structure.

After calling `_check_v2_prog' you should check at first the member
`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 `stubinfo' member of the above struct, it is valid
only, when `has_stubinfo' is nonzero.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

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


     #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;
     }


File: libc.info,  Node: chmod,  Next: _chmod,  Prev: _check_v2_prog,  Up: Alphabetical List

chmod
=====

Syntax
------

     #include <sys/stat.h>

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

Description
-----------

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

`S_IRUSR'
     Make the file readable for the owner.

`S_IWUSR'
     Make the file writable for the owner.

`S_IRGRP'
     Make the file readable for the group.

`S_IWGRP'
     Make the file writeable for the group.

`S_IROTH'
     Make the file readable for the world.

`S_IWOTH'
     Make the file writeable for the world.


Some `S_I*' constants are ignored for regular files:

   * `S_I*GRP' and `S_I*OTH' are ignored, because DOS/Windows has no
     concept of ownership, so all files are considered to belong to the
     user;

   * `S_IR*' are ignored, because files are always readable on
     DOS/Windows.

This function can be hooked by File System Extensions (*note File
System Extensions::).

Return Value
------------

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

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

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


File: libc.info,  Node: _chmod,  Next: chown,  Prev: chmod,  Up: Alphabetical List

_chmod
======

Syntax
------

     #include <io.h>

     int _chmod(const char *filename, int func, mode_t mode);

Description
-----------

This is a direct connection to the MS-DOS chmod function call, int
0x21, %ax = 0x4300/0x4301.  If FUNC is 0, then DOS is called with AX =
0x4300, which returns an attribute byte of a file.  If FUNC is 1, then
the attributes of a file are set as specified in MODE.  Note that the
directory and volume attribute bits must always be 0 when `_chmod()' is
called with FUNC = 1, or else the call will fail.  The third argument
is optional when getting attributes.  The attribute bits are defined as
follows:

       Bit       Meaning
     76543210
     .......1    Read-only
     ......1.    Hidden
     .....1..    System
     ....1...    Volume Label
     ...1....    Directory
     ..1.....    Archive
     xx......    Reserved (used by some network redirectors)

On platforms where the LFN API (*note LFN: _use_lfn.) is available,
`_chmod' calls function 0x7143 of Interrupt 21h, to support long file
names.

Return Value
------------

If the file exists, `_chmod()' returns its attribute byte in case it
succeeded, or -1 in case of failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: chown,  Next: chsize,  Prev: _chmod,  Up: Alphabetical List

chown
=====

Syntax
------

     #include <unistd.h>

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

Description
-----------

This function changes the ownership of the open file specified by FILE
to the user ID OWNER and group ID GROUP.

This function does nothing under MS-DOS.  This function can be hooked
by File System Extensions (*note File System Extensions::).

Return Value
------------

This function always returns zero if the file exists, else it returns
-1 and sets `errno' to `ENOENT'.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: chsize,  Next: cleanup_client,  Prev: chown,  Up: Alphabetical List

chsize
======

Syntax
------

     #include <io.h>

     int chsize(int handle, long size);

Description
-----------

Just calls ftruncate (*note ftruncate::).

Return Value
------------

Zero on success, -1 on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: cleanup_client,  Next: _clear87,  Prev: chsize,  Up: Alphabetical List

cleanup_client
==============

Syntax
------

     #include <debug/dbgcom.h>

     void cleanup_client (void);

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.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _clear87,  Next: __clear_fd_flags,  Prev: cleanup_client,  Up: Alphabetical List

_clear87
========

Syntax
------

     #include <float.h>

     unsigned int _clear87(void);

Description
-----------

Clears the floating point processor's exception flags.

Return Value
------------

The previous status word.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __clear_fd_flags,  Next: __clear_fd_properties,  Prev: _clear87,  Up: Alphabetical List

__clear_fd_flags
================

Syntax
------

     #include <libc/fd_props.h>

     void __clear_fd_flags(int fd, unsigned long flags);

Description
-----------

This internal function clears the combination of flags FLAGS from the
flags associated with the file descriptor FD.  The flags are some
properties that may be associated with a file descriptor (*note
__set_fd_properties::).

The caller should first check that FD has properties associated with
it, by calling `__has_fd_properties' (*note __has_fd_properties::).

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __clear_fd_properties,  Next: clearerr,  Prev: __clear_fd_flags,  Up: Alphabetical List

__clear_fd_properties
=====================

Syntax
------

     #include <libc/fd_props.h>

     int __clear_fd_properties(int fd);

Description
-----------

This internal function is called when the file descriptor FD is no
longer valid.  The usage count of the associated `fd_properties' struct
is decremented.  And if it becomes zero, this function performs cleanup
and releases the memory used by the `fd_properties' struct.

For more information, see `__set_fd_properties' (*note
__set_fd_properties::) and `__dup_fd_properties' (*note
__dup_fd_properties::).

Return Value
------------

Always returns 0 for success.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: clearerr,  Next: clock,  Prev: __clear_fd_properties,  Up: Alphabetical List

clearerr
========

Syntax
------

     #include <stdio.h>

     void clearerr(FILE *stream);

Description
-----------

This function clears the EOF and error indicators for the file STREAM.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     clearerr(stdout);


File: libc.info,  Node: clock,  Next: close,  Prev: clearerr,  Up: Alphabetical List

clock
=====

Syntax
------

     #include <time.h>

     clock_t clock(void);

Description
-----------

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

Return Value
------------

The number of tics.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

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


File: libc.info,  Node: close,  Next: _close,  Prev: clock,  Up: Alphabetical List

close
=====

Syntax
------

     #include <unistd.h>

     int close(int fd);

Description
-----------

The open file associated with FD is closed.

Return Value
------------

Zero if the file was closed, nonzero if FD was invalid or already
closed.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

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


File: libc.info,  Node: _close,  Next: closedir,  Prev: close,  Up: Alphabetical List

_close
======

Syntax
------

     #include <io.h>

     int _close(int fd);

Description
-----------

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

Return Value
------------

Zero if the file was closed, else nonzero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: closedir,  Next: clreol,  Prev: _close,  Up: Alphabetical List

closedir
========

Syntax
------

     #include <dirent.h>

     int closedir(DIR *dir);

Description
-----------

This function closes a directory opened by opendir (*note opendir::).

Return Value
------------

Zero on success, nonzero if DIR is invalid.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: clreol,  Next: clrscr,  Prev: closedir,  Up: Alphabetical List

clreol
======

Syntax
------

     #include <conio.h>

     void clreol(void);

Description
-----------

Clear to end of line.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: clrscr,  Next: confstr,  Prev: clreol,  Up: Alphabetical List

clrscr
======

Syntax
------

     #include <conio.h>

     void clrscr(void);

Description
-----------

Clear the entire screen.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: confstr,  Next: _conio_gettext,  Prev: clrscr,  Up: Alphabetical List

confstr
=======

Syntax
------

     #include <unistd.h>

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

Description
-----------

This function stores various system-dependent configuration values in
BUF.  NAME is one of the following:

`_CS_PATH'
     Returns a path to the standard POSIX utilities.

`_CS_POSIX_V6_ILP32_OFF32_CFLAGS'
     Returns the compile-time flags required to build an application
     using 32-bit `int', `long', pointer, and `off_t' types.

`_CS_POSIX_V6_ILP32_OFF32_LDFLAGS'
     Returns the link-time flags required to build an application using
     32-bit `int', `long', pointer, and `off_t' types.

`_CS_POSIX_V6_ILP32_OFF32_LIBS'
     Returns the set of libraries required to build an application
     using 32-bit `int', `long', pointer, and `off_t' types.


If LEN is not zero and NAME has a defined value, that value is copied
into BUF and null terminated.  If the length of the string to be copied
plus the null terminator is greater than LEN bytes, the string is
truncated to LEN-1 bytes and the result is null terminated.

If LEN is zero, nothing is copied into BUF and the size of the buffer
required to store the string is returned.

Return Value
------------

If 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 LEN, then BUF is truncated.

If NAME is valid but does not have a defined value, zero is returned.

If NAME is invalid, zero is returned and `errno' is set to `EINVAL'.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     char *path;
     size_t path_len;

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


File: libc.info,  Node: _conio_gettext,  Next: _conio_kbhit,  Prev: confstr,  Up: Alphabetical List

_conio_gettext
==============

Syntax
------

     #include <conio.h>

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

Description
-----------

Retrieve a block of screen characters into a buffer.

Return Value
------------

1

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _conio_kbhit,  Next: _control87,  Prev: _conio_gettext,  Up: Alphabetical List

_conio_kbhit
============

Syntax
------

     #include <conio.h>

     int _conio_kbhit(void);

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 `conio.h', the `kbhit' (*note kbhit::) function is
redefined to be this function instead.

Return Value
------------

Nonzero if a key is waiting, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: _control87,  Next: cos,  Prev: _conio_kbhit,  Up: Alphabetical List

_control87
==========

Syntax
------

     #include <float.h>

     unsigned int _control87(unsigned int newcw, unsigned int mask);

Description
-----------

This function sets and retrieves the FPU's "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:

     ---- ---- --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

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

The exception bits `MCW_EM' (the low-order 6 bits) of the control word
define the exception _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 `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
"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 `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 `PC_24',
`PC_53', and `PC_64' set the precision to 24, 53, and 64-bit mantissa,
respectively.  This feature of the coprocessor is for compatibility
with the "IEEE 745 standard" and only affect the `FADD', `FSUB'
`FSUBR', `FMUL', `FDIV', `FDIVR', and `FSQRT' instructions.  Lowering
the precision will *not* decrease the execution time of FP instructions.

The `MCW_PC' field is set to use the full-precision 64-bit mantissa by
the DJGPP startup code.

The rounding-control field `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 `MCW_IC' has no effect on 80387 and later
coprocessors.

Return Value
------------

The previous control word.

(Note that this is different from what `_control87' from the Borland C
library which returns the _new_ control word.)

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

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


File: libc.info,  Node: cos,  Next: cosh,  Prev: _control87,  Up: Alphabetical List

cos
===

Syntax
------

     #include <math.h>

     double cos(double x);

Description
-----------

This function computes the cosine of X (which should be given in
radians).

Return Value
------------

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

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Accuracy
--------

In general, this function's relative accuracy is about 1.7*10^(-16),
which is close to the machine precision for a `double'.  However, for
arguments very close to `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 cos(Pi/2) is zero, the absolute
accuracy is still very good; but if your program needs to preserve high
_relative_ accuracy for such arguments, link with `-lm' and use the
version of `cos' from `libm.a' which does elaborate argument reduction,
but is about three times slower.


File: libc.info,  Node: cosh,  Next: cprintf,  Prev: cos,  Up: Alphabetical List

cosh
====

Syntax
------

     #include <math.h>

     double cosh(double x);

Description
-----------

This function computes the hyperbolic cosine of X.

Return Value
------------

The hyperbolic cosine of X.  If the value of X is a `NaN', the return
value is `NaN' and `errno' is set to `EDOM'.  If the value of X is so
large that the result would overflow a `double', the return value is
`Inf' and `errno' is set to `ERANGE'.  If X is either a positive or a
negative infinity, the result is `+Inf', and `errno' is not changed.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: cprintf,  Next: cputs,  Prev: cosh,  Up: Alphabetical List

cprintf
=======

Syntax
------

     #include <conio.h>

     int cprintf(const char *_format, ...);

Description
-----------

Like `printf' (*note 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.

Return Value
------------

The number of characters written.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: cputs,  Next: creat,  Prev: cprintf,  Up: Alphabetical List

cputs
=====

Syntax
------

     #include <conio.h>

     int cputs(const char *_str);

Description
-----------

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

Return Value
------------

Zero on success.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: creat,  Next: _creat,  Prev: cputs,  Up: Alphabetical List

creat
=====

Syntax
------

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

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

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 MODE does not have `S_IWUSR' set.

Return Value
------------

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

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

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


File: libc.info,  Node: _creat,  Next: _creatnew,  Prev: creat,  Up: Alphabetical List

_creat
======

Syntax
------

     #include <io.h>

     int _creat(const char *path, int attrib);

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 `_creat' calls function int 0x21, %ax = 0x6c00

On platforms where the LFN API (*note LFN: _use_lfn.) is available,
`_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 (*note File
System Extensions::).  If you don't want this, you should use
`_dos_creat' (*note _dos_creat::) or `_dos_creatnew' (*note
_dos_creatnew::).

Return Value
------------

The new file descriptor, else -1 on error.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _creatnew,  Next: crlf2nl,  Prev: _creat,  Up: Alphabetical List

_creatnew
=========

Syntax
------

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

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

Description
-----------

This function creates a file given by PATH and opens it, like `_creat'
does, but only if it didn't already exist.  If the named file exists,
`_creatnew' fails.  (In contrast, `_creat' opens existing files and
overwrites their contents, see *Note _creat::.)

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

`FA_RDONLY (1)'
     The file is created with the read-only bit set.

`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.

`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.

Other bits (`FA_LABEL' and `FA_DIREC') are ignored by DOS.

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

`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.

`SH_DENYRW (10h)'
     Denies both read and write access by other processes.

`SH_DENYWR (20h)'
     Denies write access by other processes.

`SH_DENYRD (30h)'
     Denies read access by other processes.

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

Note that the file is always open for both reading and writing;
`_creatnew' ignores any bits in the lower nibble of FLAGS (`O_RDONLY',
`O_WRONLY', etc.).

`_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 FLAGS, since function 6C00h is only
supported by DOS 4.0 and later.)

The file handle returned by `_creatnew' is set to binary mode.

This function can be hooked by the Filesystem Extensions handlers, as
described in *Note File System Extensions::.  If you don't want this,
you should use `_dos_creatnew' (*note _dos_creatnew::) instead.

Return Value
------------

The new file descriptor, else -1 on error.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: crlf2nl,  Next: __crt0_glob_function,  Prev: _creatnew,  Up: Alphabetical List

crlf2nl
=======

Syntax
------

     #include <io.h>

     size_t crlf2nl(char *buf, ssize_t len);

Description
-----------

This function removes Ctrl-M characters from the given BUF.

Return Value
------------

The number of characters remaining in the buffer are returned.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __crt0_glob_function,  Next: __crt0_load_environment_file,  Prev: crlf2nl,  Up: Alphabetical List

__crt0_glob_function
====================

Syntax
------

     #include <crt0.h>

     char **__crt0_glob_function(char *_argument);

Description
-----------

If the application wishes to provide a wildcard expansion function, it
should define a `__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 `__crt0_glob_function' from the C library.
To disable expansion, provide a `__crt0_glob_function' that always
returns 0.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __crt0_load_environment_file,  Next: __crt0_setup_arguments,  Prev: __crt0_glob_function,  Up: Alphabetical List

__crt0_load_environment_file
============================

Syntax
------

     #include <crt0.h>

     void   __crt0_load_environment_file(char *_app_name);

Description
-----------

This function, provided by libc.a, does all the work required to load
additional environment variables from the file `djgpp.env' whose full
pathname is given by the `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.

*Note __crt0_setup_arguments::.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __crt0_setup_arguments,  Next: _crt0_startup_flags,  Prev: __crt0_load_environment_file,  Up: Alphabetical List

__crt0_setup_arguments
======================

Syntax
------

     #include <crt0.h>

     void   __crt0_setup_arguments(void);

Description
-----------

This function, provided by libc.a, does all the work required to
provide the two arguments passed to main() (usually `argc' and `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 `__crt0_setup_arguments_function' will
_not_ expand wildcards inside quotes (`"' or `''), 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).

*Note __crt0_load_environment_file::.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _crt0_startup_flags,  Next: cscanf,  Prev: __crt0_setup_arguments,  Up: Alphabetical List

_crt0_startup_flags
===================

Syntax
------

     #include <crt0.h>

     int _crt0_startup_flags = ...;

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.

`_CRT0_FLAG_PRESERVE_UPPER_CASE'
     If set, `argv[0]' is left in whatever case it was.  If not set, all
     characters are mapped to lower case.  Note that if the `argv0'
     field in the "stubinfo" structure is present, the case of that part
     of `argv[0]' is not affected.

`_CRT0_FLAG_USE_DOS_SLASHES'
     If set, reverse slashes (dos-style) are preserved in `argv[0]'.  If
     not set, all reverse slashes are replaced with unix-style slashes.

`_CRT0_FLAG_DROP_EXE_SUFFIX'
     If set, the `.exe' suffix is removed from the file name component
     of `argv[0]'.  If not set, the suffix remains.

`_CRT0_FLAG_DROP_DRIVE_SPECIFIER'
     If set, the drive specifier (e.g. `C:') is removed from the
     beginning of `argv[0]' (if present).  If not set, the drive
     specifier remains.

`_CRT0_FLAG_DISALLOW_RESPONSE_FILES'
     If set, response files (e.g. `@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.

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

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

`_CRT0_FLAG_FILL_DEADBEEF'
     If set, fill memory (above) with `0xdeadbeef', else fill with zero.
     This is especially useful for debugging uninitialized memory
     problems.

`_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.

`_CRT0_FLAG_NULLOK'
     If set, disable NULL pointer protection (if it can be controlled at
     all).

`_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.

`_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 `LFN'.

`_CRT0_FLAG_NONMOVE_SBRK'
     If set, the `sbrk' algorithm uses multiple DPMI memory blocks which
     makes sure the base of CS/DS/SS does not change.  This may cause
     problems with `sbrk(0)' values and programs with other assumptions
     about `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
     `sbrk'.

`_CRT0_FLAG_UNIX_SBRK'
     If set, the `sbrk' algorithm resizes memory blocks so that the
     layout of memory is set up to be the most compatible with Unix
     `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 `sbrk' behavior, you should
     set either this or the previous flag, since the default may change
     in different libc releases.

`_CRT0_DISABLE_SBRK_ADDRESS_WRAP'
     If set, non-move `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.

`_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 `sbrk''ed, so the locking may fail.
     This bit may be set or cleared during execution.  When `sbrk' uses
     multiple memory zones, it can be difficult to lock all memory
     since the memory block size and location is impossible to
     determine.

`_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', `getcwd', `_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 `FNCASE',
     *Note _preserve_fncase::.


Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: cscanf,  Next: ctermid,  Prev: _crt0_startup_flags,  Up: Alphabetical List

cscanf
======

Syntax
------

     #include <conio.h>

     int cscanf(const char *_format, ...);

Description
-----------

Like `scanf' (*note scanf::), but it reads from the standard input
device directly, avoiding buffering both by DOS and by the library.
Each character is read by `getche' (*note getche::).

Return Value
------------

The number of fields stored.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: ctermid,  Next: ctime,  Prev: cscanf,  Up: Alphabetical List

ctermid
=======

Syntax
------

     #include <unistd.h>

     char *ctermid(char *s);

Description
-----------

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

Return Value
------------

If S is null, returns pointer to internal static string "con".
Otherwise, copies "con" to buffer pointed by S.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: ctime,  Next: ctime_r,  Prev: ctermid,  Up: Alphabetical List

ctime
=====

Syntax
------

     #include <time.h>

     char *ctime(const time_t *cal);

Description
-----------

This function returns a string representing the time from CAL.  The
string returned is always 26 characters and has this format:

     Sun Jan 01 12:34:56 1993\n\0

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

Return Value
------------

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

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: ctime_r,  Next: delay,  Prev: ctime,  Up: Alphabetical List

ctime_r
=======

Syntax
------

     #include <time.h>

     char *ctime_r(const time_t *cal, char *buf);

Description
-----------

This function returns a string representing the time from CAL.  The
string returned is always 26 characters and has this format:

     Sun Jan 01 12:34:56 1993\n\0

This function is equivalent to `asctime_r(localtime_r(cal,&tm), buf)'
where TM is a variable of type `struct tm'.  *Note asctime_r::.  *Note
localtime_r::.  The buffer BUF passed must be at least 26 bytes long.

*Note ctime::, for an alternate ISO Standard interface.

Return Value
------------

A pointer to BUF containing the string representing the time.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: delay,  Next: delline,  Prev: ctime_r,  Up: Alphabetical List

delay
=====

Syntax
------

     #include <dos.h>

     void delay(unsigned msec);

Description
-----------

This function causes the program to pause for MSEC milliseconds.  It
uses the `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 <Pause> key
is pressed during the call to `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
`int 15h'.  `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.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     delay(200); /* delay for 1/5 second */


File: libc.info,  Node: delline,  Next: _detect_80387,  Prev: delay,  Up: Alphabetical List

delline
=======

Syntax
------

     #include <conio.h>

     void    delline(void);

Description
-----------

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

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: _detect_80387,  Next: difftime,  Prev: delline,  Up: Alphabetical List

_detect_80387
=============

Syntax
------

     #include <dos.h>

     int _detect_80387(void);

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.

Return Value
------------

1 if a coprocessor is present, 0 if not.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

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


File: libc.info,  Node: difftime,  Next: dirname,  Prev: _detect_80387,  Up: Alphabetical List

difftime
========

Syntax
------

     #include <time.h>

     double difftime(time_t t1, time_t t0);

Description
-----------

This function returns the difference in time, in seconds, from T0 to T1.

Return Value
------------

The number of seconds.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

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


File: libc.info,  Node: dirname,  Next: disable,  Prev: difftime,  Up: Alphabetical List

dirname
=======

Syntax
------

     #include <unistd.h>

     char * dirname (const char *fname);

Description
-----------

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

Return value
------------

The directory part in malloc'ed storage, or a NULL pointer of either
there's not enough free memory, or FNAME is a NULL pointer.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

      printf ("The parent of current directory is %s\n",
              dirname (getcwd (0, PATH_MAX)));


File: libc.info,  Node: disable,  Next: div,  Prev: dirname,  Up: Alphabetical List

disable
=======

Syntax
------

     #include <dos.h>

     int disable(void);

Description
-----------

This function disables interrupts.

*Note enable::.

Return Value
------------

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

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     int ints_were_enabled;

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


File: libc.info,  Node: div,  Next: __djgpp_exception_toggle,  Prev: disable,  Up: Alphabetical List

div
===

Syntax
------

     #include <stdlib.h>

     div_t div(int numerator, int denominator);

Description
-----------

Returns the quotient and remainder of the division NUMERATOR divided by
DENOMINATOR.  The return type is as follows:

     typedef struct {
       int quot;
       int rem;
     } div_t;

Return Value
------------

The results of the division are returned.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

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 }


File: libc.info,  Node: __djgpp_exception_toggle,  Next: __djgpp_map_physical_memory,  Prev: div,  Up: Alphabetical List

__djgpp_exception_toggle
========================

Syntax
------


     #include <sys/exceptn.h>

     void __djgpp_exception_toggle(void);

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 *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).

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------


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


File: libc.info,  Node: __djgpp_map_physical_memory,  Next: __djgpp_memory_handle,  Prev: __djgpp_exception_toggle,  Up: Alphabetical List

__djgpp_map_physical_memory
===========================

Syntax
------

     #include <dpmi.h>

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

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.  OUR_ADDR, NUM_BYTES, and PHYS_ADDR must be
page-aligned.  If they are not page-aligned, `errno' will be set to
`EINVAL' and the routine will fail.

This routine properly handles memory ranges that span multiple DPMI
handles, while `__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.

Return Value
------------

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

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     if (__djgpp_map_physical_memory (my_page_aligned_memory, 16384,
                                      0x40000000))
       printf ("Failed to map physical addresses!\n");


File: libc.info,  Node: __djgpp_memory_handle,  Next: __djgpp_memory_handle_list,  Prev: __djgpp_map_physical_memory,  Up: Alphabetical List

__djgpp_memory_handle
=====================

Syntax
------

     #include <crt0.h>

     __djgpp_sbrk_handle *__djgpp_memory_handle(unsigned address);

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.

Return Value
------------

A pointer to the __djgpp_sbrk_handle associated with a particular
address.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __djgpp_memory_handle_list,  Next: __djgpp_memory_handle_size,  Prev: __djgpp_memory_handle,  Up: Alphabetical List

__djgpp_memory_handle_list
==========================

Syntax
------

     #include <crt0.h>

     extern __djgpp_sbrk_handle __djgpp_memory_handle_list[256];

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.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);
       }


File: libc.info,  Node: __djgpp_memory_handle_size,  Next: __djgpp_nearptr_disable,  Prev: __djgpp_memory_handle_list,  Up: Alphabetical List

__djgpp_memory_handle_size
==========================

Syntax
------

     #include <crt0.h>

     extern unsigned __djgpp_memory_handle_size[256];

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.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);
       }


File: libc.info,  Node: __djgpp_nearptr_disable,  Next: __djgpp_nearptr_enable,  Prev: __djgpp_memory_handle_size,  Up: Alphabetical List

__djgpp_nearptr_disable
=======================

Syntax
------

     #include <sys/nearptr.h>

     void __djgpp_nearptr_disable(void);

Description
-----------

This function disables near pointers, and re-enables protection.  *Note
__djgpp_nearptr_enable::.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __djgpp_nearptr_enable,  Next: __djgpp_set_ctrl_c,  Prev: __djgpp_nearptr_disable,  Up: Alphabetical List

__djgpp_nearptr_enable
======================

Syntax
------

     #include <sys/nearptr.h>

     int __djgpp_nearptr_enable(void);

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 `__djgpp_conventional_base' to the linear address of the
physical memory.  For 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();
     }

The variable `__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 `malloc', `system', `spawn*', or `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!

Return Value
------------

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

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __djgpp_set_ctrl_c,  Next: __djgpp_set_page_attributes,  Prev: __djgpp_nearptr_enable,  Up: Alphabetical List

__djgpp_set_ctrl_c
==================

Syntax
------

     #include <sys/exceptn.h>

     int __djgpp_set_ctrl_c(int enable);

Description
-----------

This function sets and resets the bit which controls whether signals
`SIGINT' and `SIGQUIT' (*note 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 `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 `^C' and `^\' characters as any other character and handle them by
themselves.

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

For getting similar effects via the POSIX `termios' functions, see
*Note tcsetattr::.

Note that the effect of `Ctrl-<BREAK>' key is unaffected by this
function; use the `_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 (*Note Signal Mechanism:
signal, for more details).  Thus, if you press `Ctrl-C' while your
program calls DOS (e.g., when reading from the console), the `SIGINT'
signal handler will only be called after that call returns.

Return Value
------------

The state of `SIGINT' and `SIGQUIT' generation before the call: 0 if it
was disabled, 1 if it was enabled.  If the argument ENABLE is negative,
the state is not altered.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------


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


File: libc.info,  Node: __djgpp_set_page_attributes,  Next: __djgpp_set_sigint_key,  Prev: __djgpp_set_ctrl_c,  Up: Alphabetical List

__djgpp_set_page_attributes
===========================

Syntax
------

     #include <dpmi.h>

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

Description
-----------

This function sets the DPMI page attributes for the pages in a range of
memory.  OUR_ADDR and NUM_BYTES must be page-aligned.  If they are not
page-aligned, `errno' will be set to `EINVAL' and the routine will fail.

Consult DPMI documentation on function 0507H for the meaning of the
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.

Return Value
------------

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

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     if (__djgpp_set_page_attributes (my_page_aligned_memory, 16384, 0))
       printf ("Failed to make pages uncommitted!\n");


File: libc.info,  Node: __djgpp_set_sigint_key,  Next: __djgpp_set_sigquit_key,  Prev: __djgpp_set_page_attributes,  Up: Alphabetical List

__djgpp_set_sigint_key
======================

Syntax
------


     #include <sys/exceptn.h>

     void __djgpp_set_sigint_key(int new_key);

Description
-----------

This function changes the INTR key that generates the signal `SIGINT'.
By default, `Ctrl-C' is set as the INTR key.  To replace it with
another key, put the _scan code_ of the new INTR key into the bits 0-7
and the required keyboard status byte into bits 8-15 of NEW_KEY, and
call this function.  Here's how the keyboard status bits are defined:


        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

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 `Ctrl-C' key should be passed as `0x042e',
since the scan code of the <C> key is 2Eh, and when the <Ctrl> key is
pressed, the keyboard status byte is 04h.

To disable `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 <Shift> key doesn't
affect Ctrl- and Alt-modified keys; the right <Shift> key won't affect
them either, unless its bit is explicitly set in NEW_KEY.  This means
that `Ctrl-C' and `Ctrl-c' will both trigger `SIGINT' if `0x042e' is
passed to this function.

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

For getting similar effects via the POSIX `termios' functions, see
*Note tcsetattr::.

Return Value
------------

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

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------


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


File: libc.info,  Node: __djgpp_set_sigquit_key,  Next: __djgpp_share_flags,  Prev: __djgpp_set_sigint_key,  Up: Alphabetical List

__djgpp_set_sigquit_key
=======================

Syntax
------


     #include <sys/exceptn.h>

     void __djgpp_set_sigquit_key(int new_key);

Description
-----------

This function changes the QUIT key that generates the signal `SIGQUIT'.
By default, `Ctrl-\' is set as the QUIT key.  To replace it with
another key, put the _scan code_ of the new QUIT key into the bits 0-7
and the required keyboard status byte into bits 8-15 of NEW_KEY, and
call this function.  Here's how the keyboard status bits are defined:


        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

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 `Ctrl-\' key should be passed as `0x042b',
since the scan code of `\' is 2Bh and when the <Ctrl> key is pressed,
the keyboard status byte is 04h.

To disable `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 <Shift> key doesn't
affect Ctrl- and Alt-modified keys; the right <Shift> key won't affect
them either, unless its bit is explicitly set in NEW_KEY.  This means
that `Ctrl-\' and `Ctrl-|' will both trigger `SIGQUIT' if `0x042b' is
passed to this function.

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

For getting similar effects via the POSIX `termios' functions, see
*Note tcsetattr::.

Return Value
------------

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

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------


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


File: libc.info,  Node: __djgpp_share_flags,  Next: __djgpp_spawn,  Prev: __djgpp_set_sigquit_key,  Up: Alphabetical List

__djgpp_share_flags
===================

Syntax
------

     #include <fcntl.h>

     int __djgpp_share_flags = ...;

Description
-----------

This variable controls the share flags used by `open' (and hence
`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 `open' call then these flags
will remain untouched. In this way `__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 `SHARE.EXE'.

The available flags are:

`SH_COMPAT	0x0000'
     That's the compatible mode.

`SH_DENYRW	0x0010'
     Deny read and deny write.

`SH_DENYWR	0x0020'
     Deny write.

`SH_DENYRD	0x0030'
     Deny read.

`SH_DENYNO	0x0040'
     No deny.


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

*Note open::.  *Note fopen::.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __djgpp_spawn,  Next: __djgpp_traceback_exit,  Prev: __djgpp_share_flags,  Up: Alphabetical List

__djgpp_spawn
=============

Syntax
------

     #include <process.h>

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

Description
-----------

This function runs other programs like `spawnve' (*note spawn*::) except
that an additional parameter FLAGS is passed.  FLAGS can include the
following flags to control the details of finding the program to run:

`SPAWN_EXTENSION_SRCH'
     If an extension is not included in PATH, search for a file PATH
     with the extensions `.com', `.exe', `.bat', and `.btm'.

`SPAWN_NO_EXTENSION_SRCH'
     Do not perform an extension search.  If the file has an extension,
     it must already be included in PATH.


Return Value
------------

*Note spawn*::.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: __djgpp_traceback_exit,  Next: _djstat_describe_lossage,  Prev: __djgpp_spawn,  Up: Alphabetical List

__djgpp_traceback_exit
======================

Syntax
------


     #include <signal.h>

     void __djgpp_traceback_exit(int signo);

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 `SIGQUIT' is raised (`SIGQUIT' is by default
discarded).

You can use this function to get the Unix behavior of aborting the
program on `SIGQUIT' (see the example below).

When this function is called directly, pass the signal number as its
SIGNO argument.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

       signal(SIGQUIT, __djgpp_traceback_exit);


File: libc.info,  Node: _djstat_describe_lossage,  Next: _djstat_fail_bits,  Prev: __djgpp_traceback_exit,  Up: Alphabetical List

_djstat_describe_lossage
========================

Syntax
------

     #include <stdio.h>

     void _djstat_describe_lossage(FILE *fp);

Description
-----------

Accesses the global variable `_djstat_fail_bits' (*note
_djstat_fail_bits::) and prints to the stream given by FP a
human-readable description of the undocumented DOS features which the
last call to `stat()' or `fstat()' failed to use.  (If FP is zero, the
function prints to stderr.)  If the last call to `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 `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 ("Swappable DOS Area") - this is an internal DOS structure.
`stat()' uses it to get the full directory entry (including the
starting cluster number) of a file.  The pointer to SDA found by
`stat()' is trusted only if we find the pathname of our file at a
specific offset in that SDA.

SFT ("System File Table") - another internal DOS structure, used in
file operations.  `fstat()' uses it to get full information on a file
given its handle.  An SFT entry which is found by `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.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

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


File: libc.info,  Node: _djstat_fail_bits,  Next: _djstat_flags,  Prev: _djstat_describe_lossage,  Up: Alphabetical List

_djstat_fail_bits
=================

Syntax
------

     #include <sys/stat.h>

     extern unsigned short   _djstat_fail_bits;

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

The following bits are currently defined:

`_STFAIL_SDA'
     Indicates that Get SDA call failed.

`_STFAIL_OSVER'
     Indicates an unsupported DOS version (less than 3.10 for `stat' or
     less than 2.0 for `fstat').

`_STFAIL_BADSDA'
     The pointer to SDA was found to be bogus.

`_STFAIL_TRUENAME'
     Indicates that `_truename' (*note _truename::) function call
     failed.

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

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

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

`_STFAIL_WRITEBIT'
     `fstat' was asked to get write access bit of a file, but couldn't.

`_STFAIL_DEVNO'
     `fstat' failed to get device number.

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

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

`_STFAIL_SFTNF'
     The file entry was not found in the SFT array.


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 `_djstat_describe_lossage'
(*note _djstat_describe_lossage::).

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

SFT ("System File Table") - another internal DOS structure, used in
file operations.  `fstat' uses it to get full information on a file
given its handle.  An SFT entry which is found by `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.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _djstat_flags,  Next: dlclose,  Prev: _djstat_fail_bits,  Up: Alphabetical List

_djstat_flags
=============

Syntax
------

     #include <sys/stat.h>

     extern unsigned short   _djstat_flags;

This variable contains bits for some fields of `struct stat' which are
expensive to compute under DOS.  Any such computation is only done by
`stat' (*note stat::) or `fstat' (*note fstat::) if the corresponding
bit in `_djstat_flags' is _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:

`_STAT_INODE'
     Causes `stat' and `fstat' to compute the `st_ino' (inode number)
     field.

`_STAT_EXEC_EXT'
     Tells `stat' and `fstat' to compute the execute access bit from
     the file-name extension.  `stat' and `fstat' know about many
     popular file-name extensions, to speed up the computation of the
     execute access bit.

`_STAT_EXEC_MAGIC'
     Tells `stat' and `fstat' to compute the execute access bit from
     magic signature (the first two bytes of the file).  Use
     `_is_executable' (*note _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 `stat' and `fstat' (because it
     requires to read the first two bytes of every file).  If your
     application doesn't care about execute access bit, setting
     `_STAT_EXEC_MAGIC' will significantly speed it up.

     Note that if `_STAT_EXEC_MAGIC' is set, but `_STAT_EXEC_EXT' is
     not, some files which shouldn't be flagged as executables (e.g.,
     COFF `*.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 `is_exec.c' file.

`_STAT_DIRSIZE'
     Causes `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 `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 `st_nlink' member,
     you should set the `_STAT_DIRSIZE' bit in `_djstat_flags'.

`_STAT_ROOT_TIME'
     Causes `stat' to try to get time stamp of root directory from its
     volume label entry, if there is one.

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


Note that if you set a bit, some failure bits in `_djstat_fail_bits'
(*note _djstat_fail_bits::) might not be set, because some computations
which report failures are only done when they are required.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: dlclose,  Next: dlerror,  Prev: _djstat_flags,  Up: Alphabetical List

dlclose
=======

Syntax
------

     #include <dlfcn.h>

     int dlclose (void *handle);

Description
-----------

This function closes a dynamic module loaded with `dlopen' (*note
dlopen::).  The memory is freed and all pointers into that image become
invalid.

Return Value
------------

Returns 0 on success, non-zero value on failure.  More detailed error
information can be obtained using `dlerror' (*note dlerror::).

Portability
-----------

ANSI/ISO C   No
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992


File: libc.info,  Node: dlerror,  Next: dlerrstatmod,  Prev: dlclose,  Up: Alphabetical List

dlerror
=======

Syntax
------

     #include <dlfcn.h>

     char *dlerror (void);

Description
-----------

This function returns a character string with more information on the
last error that occurred during dynamic linking processing.

Return Value
------------

Returns `NULL' if no errors, pointer to error string if available.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992


File: libc.info,  Node: dlerrstatmod,  Next: dlerrstatsym,  Prev: dlerror,  Up: Alphabetical List

dlerrstatmod
============

Syntax
------

     #include <sys/dxe.h>

     extern void (*dlerrstatmod) (const char *module);

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.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: dlerrstatsym,  Next: dlopen,  Prev: dlerrstatmod,  Up: Alphabetical List

dlerrstatsym
============

Syntax
------

     #include <sys/dxe.h>

     extern void (*dlerrstatsym) (const char *module, const char *symbol);

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.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: dlopen,  Next: dlregsym,  Prev: dlerrstatsym,  Up: Alphabetical List

dlopen
======

Syntax
------

     #include <dlfcn.h>

     void *dlopen (const char *filename, int mode);

Description
-----------

This function loads a dynamic executable image, whose file name is
pointed to by FILENAME, into memory and returns a handle associated
with the image for use with the `dlsym' (*note dlsym::) and `dlclose'
(*note dlclose::) functions.

If FILENAME contains a path it is used, else it searches the path
specified by the environment variable `LD_LIBRARY_PATH' and
`SYSTEM_DXE_PATH'. DJGPP own search paths are specified in
`SYSTEM_DXE_PATH'. User may add additional search path by defining then
in `LD_LIBRARY_PATH'. The typical extension used is `.DXE', and these
dynamic loadable images are created using `dxe3gen' (*note dxe3gen:
(utils)dxe3gen.).

The MODE field is a combination of `RTLD_xxx' flags, of which only
`RTLD_GLOBAL' works (others are defined in `dlfcn.h' for Unix
compatibility).  The `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.

Return Value
------------

`NULL' on failure, handle for the loaded image on success.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992


File: libc.info,  Node: dlregsym,  Next: dlsym,  Prev: dlopen,  Up: Alphabetical List

dlregsym
========

Syntax
------

     #include <sys/dxe.h>

     int dlregsym (const dxe_symbol_table *symtab);

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 `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.

Return Value
------------

Returns number of symbol tables in use.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: dlsym,  Next: _dlsymresolver,  Prev: dlregsym,  Up: Alphabetical List

dlsym
=====

Syntax
------

     #include <dlfcn.h>

     void *dlsym (void *handle, const char *symbol_name);

Description
-----------

This function get the address of a symbol defined in a shared loadable
image.

The HANDLE argument is the value returned from a call to `dlopen', or
the special value `RTLD_DEFAULT' which will search all symbols in the
global scope.

The SYMBOL_NAME is the assembler name, not the C name.  For DJGPP/COFF
prepend an underscore in front.

Return Value
------------

Returns `NULL' on failure, pointer to requested symbol on success.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992


File: libc.info,  Node: _dlsymresolver,  Next: dlunregsym,  Prev: dlsym,  Up: Alphabetical List

_dlsymresolver
==============

Syntax
------

     #include <sys/dxe.h>

     extern void *(*_dlsymresolver) (const char *symname);

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.

Return Value
------------

The handler should return `NULL' to rise a error condition, otherwise
it should return a valid address.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: dlunregsym,  Next: _doprnt,  Prev: _dlsymresolver,  Up: Alphabetical List

dlunregsym
==========

Syntax
------

     #include <sys/dxe.h>

     int dlunregsym (const dxe_symbol_table *symtab);

Description
-----------

This function removes a table of symbols exported into the loaded
modules.  For completeness - the inverse of `dlregsym' and rarely used.

Return Value
------------

Returns number of symbol tables in use if success, -1 on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _doprnt,  Next: _dos_close,  Prev: dlunregsym,  Up: Alphabetical List

_doprnt
=======

Syntax
------

     #include <stdio.h>

     int _doprnt(const char *format, void *params, FILE *file);

Description
-----------

This is an internal function that is used by all the `printf' style
functions, which simply pass their format, arguments, and stream to this
function.

*Note printf::, for a discussion of the allowed formats and arguments.

Return Value
------------

The number of characters generated is returned.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     int args[] = { 1, 2, 3, 66 };
     _doprnt("%d %d %d %c\n", args, stdout);


File: libc.info,  Node: _dos_close,  Next: _dos_commit,  Prev: _doprnt,  Up: Alphabetical List

_dos_close
==========

Syntax
------

     #include <dos.h>

     unsigned int _dos_close(int handle);

Description
-----------

This is a direct connection to the MS-DOS close function call (%ah =
0x3E).  This function closes the specified file.

*Note _dos_open::. *Note _dos_creat::. *Note _dos_creatnew::.  *Note
_dos_read::. *Note _dos_write::.

Return Value
------------

Returns 0 if successful or DOS error code on error (and sets `errno').

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     int handle;

     _dos_creat("FOO.DAT", _A_ARCH, &handle);
     ...
     _dos_close(handle);


File: libc.info,  Node: _dos_commit,  Next: _dos_creat,  Prev: _dos_close,  Up: Alphabetical List

_dos_commit
===========

Syntax
------

     #include <dos.h>

     unsigned int _dos_commit(int handle);

Description
-----------

This is a direct connection to the MS-DOS commit function call (%ah =
0x68).  This function flushes DOS internal file buffers to disk.

Return Value
------------

Returns 0 if successful or DOS error code on error (and sets `errno').

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     _dos_write(handle, buffer, 1000, &result);
     _dos_commit(handle);
     _dos_close(handle);


File: libc.info,  Node: _dos_creat,  Next: _dos_creatnew,  Prev: _dos_commit,  Up: Alphabetical List

_dos_creat
==========

Syntax
------

     #include <dos.h>

     unsigned int _dos_creat(const char *filename, unsigned short attr,
                             int *handle);

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 HANDLE if creating is successful. If the file
already exists it truncates the file to zero length. Meaning of ATTR
parameter is the following:

`_A_NORMAL (0x00)'
     Normal file (no read/write restrictions)

`_A_RDONLY (0x01)'
     Read only file

`_A_HIDDEN (0x02)'
     Hidden file

`_A_SYSTEM (0x04)'
     System file

`_A_ARCH (0x20)'
     Archive file


See also *Note _dos_open::, *Note _dos_creatnew::, *Note _dos_read::,
*Note _dos_write::, and *Note _dos_close::.

This function does not support long filenames, even on systems where the
LFN API (*note LFN: _use_lfn.) is available.  For LFN-aware functions
with similar functionality see *Note _creat::, and *Note _creatnew::.
Also see *Note creat::, and *Note open::, which are Posix-standard.

Return Value
------------

Returns 0 if successful or DOS error code on error (and sets `errno')

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     int handle;

     if ( !_dos_creat("FOO.DAT", _A_ARCH, &handle) )
        puts("Creating was successful !");


File: libc.info,  Node: _dos_creatnew,  Next: _dos_findfirst,  Prev: _dos_creat,  Up: Alphabetical List

_dos_creatnew
=============

Syntax
------

     #include <dos.h>

     unsigned int _dos_creatnew(const char *filename, unsigned short attr,
                                int *handle);

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 HANDLE if creating is successful.
This function will fail if the specified file exists.  Meaning of ATTR
parameter is the following:

`_A_NORMAL (0x00)'
     Normal file (no read/write restrictions)

`_A_RDONLY (0x01)'
     Read only file

`_A_HIDDEN (0x02)'
     Hidden file

`_A_SYSTEM (0x04)'
     System file

`_A_ARCH (0x20)'
     Archive file


See also *Note _dos_open::, *Note _dos_creat::, *Note _dos_read::,
*Note _dos_write::, and *Note _dos_close::.

This function does not support long filenames, even on systems where the
LFN API (*note LFN: _use_lfn.) is available.  For LFN-aware functions
with similar functionality see *Note _creatnew::, and *Note _creat::.
Also see *Note creat::, and *Note open::, which are Posix-standard.

Return Value
------------

Returns 0 if successful or DOS error code on error (and sets `errno').

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     int handle;

     if ( !_dos_creatnew("FOO.DAT", _A_NORMAL, &handle) )
        puts("Creating was successful !");


File: libc.info,  Node: _dos_findfirst,  Next: _dos_findnext,  Prev: _dos_creatnew,  Up: Alphabetical List

_dos_findfirst
==============

Syntax
------

     #include <dos.h>

     unsigned int _dos_findfirst(char *name, unsigned int attr,
                                 struct find_t *result);

Description
-----------

This function and the related `_dos_findnext' (*note _dos_findnext::)
are used to scan directories for the list of files therein. The NAME is
a wildcard that specifies the directory and files to search. RESULT is
a structure to hold the results and state of the search, and ATTR is a
combination of the following:

`_A_NORMAL (0x00)'
     Normal file (no read/write restrictions)

`_A_RDONLY (0x01)'
     Read only file

`_A_HIDDEN (0x02)'
     Hidden file

`_A_SYSTEM (0x04)'
     System file

`_A_VOLID (0x08)'
     Volume ID file

`_A_SUBDIR (0x10)'
     Subdirectory

`_A_ARCH (0x20)'
     Archive file


The results are returned in a `struct find_t' defined on `<dos.h>' as
follows:

     struct find_t {
       char reserved[21];
       unsigned char attrib;
       unsigned short wr_time;
       unsigned short wr_date;
       unsigned long size;
       char name[256];
     };

*Note _dos_findnext::.

This function does not support long filenames, even on systems where the
LFN API (*note LFN: _use_lfn.) is available.  For LFN-aware functions
with similar functionality see *Note findfirst::, and *Note findnext::.
Also see *Note opendir::, and *Note readdir::, which are Posix-standard.

Return Value
------------

Zero if a match is found, DOS error code if not found (and sets
`errno').

Portability
-----------

ANSI/ISO C   No
POSIX        No

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) );
     }


File: libc.info,  Node: _dos_findnext,  Next: _dos_getdate,  Prev: _dos_findfirst,  Up: Alphabetical List

_dos_findnext
=============

Syntax
------

     #include <dos.h>

     unsigned int _dos_findnext(struct find_t *result);

Description
-----------

This finds the next file in the search started by `_dos_findfirst'.
See *Note _dos_findfirst::, for the description of `struct find_t'.

This function does not support long filenames, even on systems where the
LFN API (*note LFN: _use_lfn.) is available.  For LFN-aware functions
with similar functionality see *Note findfirst::, and *Note findnext::.
Also see *Note opendir::, and *Note readdir::, which are Posix-standard.

Return Value
------------

Zero if a match is found, DOS error code if not found (and sets
`errno').

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _dos_getdate,  Next: _dos_getdiskfree,  Prev: _dos_findnext,  Up: Alphabetical List

_dos_getdate
============

Syntax
------

     #include <dos.h>

     void _dos_getdate(struct dosdate_t *date);

Description
-----------

This function gets the current date and fills the DATE structure with
these values.

     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 */
     };

*Note _dos_setdate::. *Note _dos_gettime::. *Note _dos_settime::.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     struct dosdate_t date;

     _dos_getdate(&date);


File: libc.info,  Node: _dos_getdiskfree,  Next: _dos_getdrive,  Prev: _dos_getdate,  Up: Alphabetical List

_dos_getdiskfree
================

Syntax
------

     #include <dos.h>

     unsigned int _dos_getdiskfree(unsigned int drive,
                                   struct diskfree_t *diskspace);

Description
-----------

This function determines the free space on DRIVE drive (0=default,
1=A:, 2=B:, etc.) and fills DISKSPACE structure.  The members of
`struct diskfree_t' are defined by `<dos.h>' as follows:

     struct diskfree_t {
       unsigned short total_clusters;
       unsigned short avail_clusters;
       unsigned short sectors_per_cluster;
       unsigned short bytes_per_sector;
     };

Return Value
------------

Returns with 0 if successful, non-zero on error (and sets `errno' to
`EINVAL').

Portability
-----------

ANSI/ISO C   No
POSIX        No

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");


File: libc.info,  Node: _dos_getdrive,  Next: _dos_getfileattr,  Prev: _dos_getdiskfree,  Up: Alphabetical List

_dos_getdrive
=============

Syntax
------

     #include <dos.h>

     void _dos_getdrive(unsigned int *p_drive);

Description
-----------

This function determine the current default drive and writes this value
into P_DRIVE (1=A:, 2=B:, etc.).

*Note _dos_setdrive::.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     unsigned int drive;

     _dos_getdrive(&drive);
     printf("The current drive is %c:.\n", 'A' - 1 + drive);


File: libc.info,  Node: _dos_getfileattr,  Next: _dos_getftime,  Prev: _dos_getdrive,  Up: Alphabetical List

_dos_getfileattr
================

Syntax
------

     #include <dos.h>

     unsigned int _dos_getfileattr(const char *filename,
                                   unsigned int *p_attr);

Description
-----------

This function determines the attributes of given file and fills ATTR
with it. Use the following constants (in DOS.H) to check this value.

`_A_NORMAL (0x00)'
     Normal file (no read/write restrictions)

`_A_RDONLY (0x01)'
     Read only file

`_A_HIDDEN (0x02)'
     Hidden file

`_A_SYSTEM (0x04)'
     System file

`_A_VOLID (0x08)'
     Volume ID file

`_A_SUBDIR (0x10)'
     Subdirectory

`_A_ARCH (0x20)'
     Archive file


*Note _dos_setfileattr::.

This function does not support long filenames, even on systems where the
LFN API (*note LFN: _use_lfn.) is available.  For LFN-aware functions
with similar functionality see *Note _chmod::.  Also see *Note chmod::,
*Note access::, and *Note stat::, which are Posix-standard.

Return Value
------------

Returns with 0 if successful and DOS error value on error (and sets
`errno'=ENOENT).

Portability
-----------

ANSI/ISO C   No
POSIX        No

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.");


File: libc.info,  Node: _dos_getftime,  Next: _dos_gettime,  Prev: _dos_getfileattr,  Up: Alphabetical List

_dos_getftime
=============

Syntax
------

     #include <dos.h>

     unsigned int _dos_getftime(int handle,
                                unsigned int *p_date, unsigned *p_time);

Description
-----------

This function gets the date and time of the given file and puts these
values into P_DATE and P_TIME variable. The meaning of DOS date in the
P_DATE variable is the following:

     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

The meaning of DOS time in the P_TIME variable is the following:

     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

*Note _dos_setftime::.

This function cannot be used to return last access and creation date and
time, even on systems where the LFN API (*note LFN: _use_lfn.) is
available.  See *Note _lfn_get_ftime::, for a function that can be used
to get the other two times.  Also see *Note fstat::, which is
Posix-standard.

Return Value
------------

Returns 0 if successful and return DOS error on error (and sets
`errno'=EBADF).

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: _dos_gettime,  Next: _dos_lk64,  Prev: _dos_getftime,  Up: Alphabetical List

_dos_gettime
============

Syntax
------

     #include <dos.h>

     void _dos_gettime(struct dostime_t *time);

Description
-----------

This function gets the current time and fills the TIME structure with
these values.

     struct dostime_t {
       unsigned char hour;     /* 0-23 */
       unsigned char minute;   /* 0-59 */
       unsigned char second;   /* 0-59 */
       unsigned char hsecond;  /* 0-99 */
     };

*Note _dos_settime::. *Note _dos_getdate::. *Note _dos_setdate::.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     struct dostime_t time;

     _dos_gettime(&time);


File: libc.info,  Node: _dos_lk64,  Next: _dos_lock,  Prev: _dos_gettime,  Up: Alphabetical List

_dos_lk64
=========

Syntax
------

     #include <io.h>

     int _dos_lk64(int fd, long long offset, long long length);

Description
-----------

Adds an advisory lock to the specified region of the file.

Arguments OFFSET and LENGTH must be of type `long long', thus enabling
you to lock with offsets and lengths as large as ~2^63 (FAT16 limits
this to ~2^31; FAT32 limits this to 2^32-2).

*Note _dos_unlk64::.

Return Value
------------

Zero if the lock was added, nonzero otherwise.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _dos_lock,  Next: _dos_open,  Prev: _dos_lk64,  Up: Alphabetical List

_dos_lock
=========

Syntax
------

     #include <io.h>

     int _dos_lock(int fd, long offset, long length);

Description
-----------

Adds an advisory lock to the specified region of the file.

Return Value
------------

Zero if the lock was added, nonzero otherwise.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _dos_open,  Next: _dos_read,  Prev: _dos_lock,  Up: Alphabetical List

_dos_open
=========

Syntax
------

     #include <fcntl.h>
     #include <share.h>
     #include <dos.h>

     unsigned int _dos_open(const char *filename, unsigned short mode,
                            int *handle);

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 HANDLE if opening is successful.  Meaning of MODE
parameter is the following:

Access mode bits (in FCNTL.H):
`O_RDONLY (_O_RDONLY) 0x00'
     Open for read only

`O_WRONLY (_O_WRONLY) 0x01'
     Open for write only

`O_RDWR (_O_RDWR) 0x02'
     Open for read and write


Sharing mode bits (in SHARE.H):
`SH_COMPAT (_SH_COMPAT) 0x00'
     Compatibility mode

`SH_DENYRW (_SH_DENYRW) 0x10'
     Deny read/write mode

`SH_DENYWR (_SH_DENYWR) 0x20'
     Deny write mode

`SH_DENYRD (_SH_DENYRD) 0x30'
     Deny read mode

`SH_DENYNO (_SH_DENYNO) 0x40'
     Deny none mode


Inheritance bits (in FCNTL.H):
`O_NOINHERIT (_O_NOINHERIT) 0x80'
     File is not inherited by child process


See also *Note _dos_creat::, *Note _dos_creatnew::, *Note _dos_read::,
*Note _dos_write::, and *Note _dos_close::.

This function does not support long filenames, even on systems where the
LFN API (*note LFN: _use_lfn.) is available.  For LFN-aware functions
with similar functionality see *Note _open::, *Note _creat::, and *Note
_creatnew::.  Also see *Note open::, and *Note creat::, which are
Posix-standard.

Return Value
------------

Returns 0 if successful or DOS error code on error (and sets `errno' to
EACCES, EINVAL, EMFILE or ENOENT).

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     int handle;

     if ( !_dos_open("FOO.DAT", O_RDWR, &handle) )
        puts("Wow, file opening was successful !");


File: libc.info,  Node: _dos_read,  Next: _dos_setdate,  Prev: _dos_open,  Up: Alphabetical List

_dos_read
=========

Syntax
------

     #include <dos.h>

     unsigned int _dos_read(int handle, void *buffer, unsigned int count,
                            unsigned int *result);

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 HANDLE into BUFFER COUNT bytes.  COUNT
value may be arbitrary size (for example > 64KB).  It puts number of
bytes read into RESULT if reading is successful.

See also *Note _dos_open::, *Note _dos_creat::, *Note _dos_creatnew::,
*Note _dos_write::, and *Note _dos_close::.

Return Value
------------

Returns 0 if successful or DOS error code on error (and sets `errno' to
EACCES or EBADF)

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);
     }


File: libc.info,  Node: _dos_setdate,  Next: _dos_setdrive,  Prev: _dos_read,  Up: Alphabetical List

_dos_setdate
============

Syntax
------

     #include <dos.h>

     unsigned int _dos_setdate(struct dosdate_t *date);

Description
-----------

This function sets the current date. The DOSDATE_T structure is as
follows:

     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 */
     };

DAYOFWEEK field has no effect at this function call.

*Note _dos_getdate::. *Note _dos_gettime::. *Note _dos_settime::.

Return Value
------------

Returns 0 if successful and non-zero on error (and sets `errno'=EINVAL).

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     struct dosdate_t date;

     date->year  = 1999;
     date->month = 12;
     date->day   = 31;
     if ( !_dos_setdate(&date) )
       puts("It was a valid date.");


File: libc.info,  Node: _dos_setdrive,  Next: _dos_setfileattr,  Prev: _dos_setdate,  Up: Alphabetical List

_dos_setdrive
=============

Syntax
------

     #include <dos.h>

     void _dos_setdrive(unsigned int drive, unsigned int *p_drives);

Description
-----------

This function set the current default drive based on DRIVE (1=A:, 2=B:,
etc.) and determines the number of available logical drives and fills
P_DRIVES with it.

*Note _dos_getdrive::.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: _dos_setfileattr,  Next: _dos_setftime,  Prev: _dos_setdrive,  Up: Alphabetical List

_dos_setfileattr
================

Syntax
------

     #include <dos.h>

     unsigned int _dos_setfileattr(const char *filename, unsigned int attr);

Description
-----------

This function sets the attributes of given file. Use the following
constants in DOS.H to create ATTR parameter:

`_A_NORMAL (0x00)'
     Normal file (no read/write restrictions)

`_A_RDONLY (0x01)'
     Read only file

`_A_HIDDEN (0x02)'
     Hidden file

`_A_SYSTEM (0x04)'
     System file

`_A_VOLID (0x08)'
     Volume ID file

`_A_SUBDIR (0x10)'
     Subdirectory

`_A_ARCH (0x20)'
     Archive file


*Note _dos_getfileattr::.

This function does not support long filenames, even on systems where the
LFN API (*note LFN: _use_lfn.) is available.  For LFN-aware functions
with similar functionality see *Note _chmod::.  Also see *Note chmod::,
which is Posix-standard.

Return Value
------------

Returns with 0 if successful and DOS error value on error (and sets
`errno' to ENOENT or EACCES).

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     if ( !_dos_setfileattr("FOO.DAT", _A_RDONLY | _A_HIDDEN) )
        puts("FOO.DAT is hidden now.");


File: libc.info,  Node: _dos_setftime,  Next: _dos_settime,  Prev: _dos_setfileattr,  Up: Alphabetical List

_dos_setftime
=============

Syntax
------

     #include <dos.h>

     unsigned int _dos_setftime(int handle,
                                unsigned int date, unsigned time);

Description
-----------

This function sets the date and time of the given file. The meaning of
DOS date in the DATE variable is the following:

     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

The meaning of DOS time in the TIME variable is the following:

     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

*Note _dos_getftime::.

This function cannot be used to set the last access date and time, even
on systems where the LFN API (*note LFN: _use_lfn.) is available.  For
LFN-aware functions with similar functionality see *Note utime::, which
is Posix-standard, and see *Note utimes::.

Return Value
------------

Returns 0 if successful and return DOS error on error (and sets
`errno'=EBADF).

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: _dos_settime,  Next: _dos_unlk64,  Prev: _dos_setftime,  Up: Alphabetical List

_dos_settime
============

Syntax
------

     #include <dos.h>

     void _dos_settime(struct dostime_t *time);

Description
-----------

This function sets the current time. The TIME structure is as follows:

     struct dostime_t {
       unsigned char hour;     /* 0-23 */
       unsigned char minute;   /* 0-59 */
       unsigned char second;   /* 0-59 */
       unsigned char hsecond;  /* 0-99 */
     };

*Note _dos_gettime::. *Note _dos_getdate::. *Note _dos_setdate::.

Return Value
------------

Returns 0 if successful and non-zero on error (and sets `errno'=EINVAL).

Portability
-----------

ANSI/ISO C   No
POSIX        No

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.");


File: libc.info,  Node: _dos_unlk64,  Next: _dos_unlock,  Prev: _dos_settime,  Up: Alphabetical List

_dos_unlk64
===========

Syntax
------

     #include <io.h>

     int _dos_unlk64(int fd, long long offset, long long length);

Description
-----------

Removes an advisory lock to the specified region of the file.

Arguments OFFSET and LENGTH must be of type `long long', thus enabling
you to unlock with offsets and lengths as large as ~2^63 (FAT16 limits
this to ~2^31; FAT32 limits this to 2^32-2).

*Note _dos_lk64::.

Return Value
------------

Zero if the lock was removed, nonzero otherwise.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _dos_unlock,  Next: _dos_write,  Prev: _dos_unlk64,  Up: Alphabetical List

_dos_unlock
===========

Syntax
------

     #include <io.h>

     _dos_unlock(int fd, long offset, long length);

Description
-----------

Removes an advisory lock to the specified region of the file.

Return Value
------------

Zero if the lock was removed, nonzero otherwise.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _dos_write,  Next: _doscan,  Prev: _dos_unlock,  Up: Alphabetical List

_dos_write
==========

Syntax
------

     #include <dos.h>

     unsigned int _dos_write(int handle,
                             const void *buffer, unsigned int count,
                             unsigned int *result);

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 COUNT bytes from BUFFER to HANDLE.  COUNT
value may be arbitrary size (e.g. > 64KB).  It puts the number of bytes
written into RESULT if writing is successful.

See also *Note _dos_open::, *Note _dos_creat::, *Note _dos_creatnew::,
*Note _dos_read::, and *Note _dos_close::.

Return Value
------------

Returns 0 if successful or DOS error code on error (and sets `errno' to
EACCES or EBADF)

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);
     }


File: libc.info,  Node: _doscan,  Next: _doserrno,  Prev: _dos_write,  Up: Alphabetical List

_doscan
=======

Syntax
------

     #include <stdarg.h>
     #include <stdio.h>

     int _doscan(FILE *file, const char *format, va_list argp);

Description
-----------

This is an internal function that is used by all the `scanf' style
functions, which simply pass their format, arguments, and stream to this
function.

*Note scanf::, for a discussion of the allowed formats and arguments.

Return Value
------------

The number of characters successfully scanned is returned, or -1 on
error.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: _doserrno,  Next: __dosexec_find_on_path,  Prev: _doscan,  Up: Alphabetical List

_doserrno
=========

Syntax
------

     #include <errno.h>

     extern int _doserrno;

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 *Note
dosexterr::.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

      _doserrno = 0;
      fprintf (stdprn, "Hello, world!\r\n\f");
      if (_doserrno == 0x1c)
        fprintf (stderr, "The printer is out of paper!\n");


File: libc.info,  Node: __dosexec_find_on_path,  Next: dosexterr,  Prev: _doserrno,  Up: Alphabetical List

__dosexec_find_on_path
======================

Syntax
------

     #include <stdio.h>
     #include <libc/dosexec.h>

     char *__dosexec_find_on_path(const char *program,
                                  char *envp[], char *buf);

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. `.exe'.
These executable extensions are described for the `spawn*()' function
(*note spawn*::).

Pass the program name in PROGRAM, the environment array in ENVP and the
output buffer in BUF.  ENVP is an array of pointers to the environment
variables; it must be terminated with a `NULL' pointer.  BUF must be
large enough to hold at least `FILENAME_MAX' bytes.

ENVP controls where `__dosexec_find_on_path' looks for the program.  If
ENVP is `NULL', then only the current directory is searched.  If ENVP
contains the `PATH' environment variable whose value lists several
directories, then these directories are also searched.  The global
variable `environ' is usually passed for ENVP.

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
`PATH' as recorded in ENVP, it puts the full pathname into BUF and
returns a pointer to BUF.  Otherwise, it returns `NULL'.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

      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);


File: libc.info,  Node: dosexterr,  Next: dosmemget,  Prev: __dosexec_find_on_path,  Up: Alphabetical List

dosexterr
=========

Syntax
------

     #include <dos.h>

     int dosexterr(struct DOSERROR *p_error);

Description
-----------

This function reads extended error information from DOS and fills
P_ERROR structure.

     struct DOSERROR {
       int  exterror;
       char class;
       char action;
       char locus;
     };

Values for DOS extended error code (EXTERR field):
     ---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

Values for error class (CLASS field):
      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

Values for suggested action (ACTION field):
      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

Values for error locus (LOCUS field):
      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

Return Value
------------

Returns with the extended error code.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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;
     }


File: libc.info,  Node: dosmemget,  Next: dosmemgetb,  Prev: dosexterr,  Up: Alphabetical List

dosmemget
=========

Syntax
------

     #include <sys/movedata.h>

     void dosmemget(int offset, int length, void *buffer);

Description
-----------

This function transfers data from MS-DOS's conventional memory space to
the program's virtual address space.  The OFFSET is a physical address,
which can be computed from a real-mode segment/offset pair as follows:

     offset = segment * 16 + offset;

The LENGTH is the number of bytes to transfer, and BUFFER is a pointer
to somewhere in your virtual address space (such as memory obtained
from `malloc') where the data will go.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     unsigned short shift_state;
     dosmemget(0x417, 2, &shift_state);
     if (shift_state & 0x0004)
       /* Ctrl key pressed */;


File: libc.info,  Node: dosmemgetb,  Next: dosmemgetl,  Prev: dosmemget,  Up: Alphabetical List

dosmemgetb
==========

Syntax
------

     #include <sys/movedata.h>

     void _dosmemgetb(unsigned long offset, size_t xfers, void *buffer);

Description
-----------

This function transfers data from MS-DOS's conventional memory space to
the program's virtual address space, using only byte transfers.  The
OFFSET is a physical address, which can be computed from a real-mode
segment/offset pair as follows:

     offset = segment * 16 + offset;

The XFERS is the number of bytes to transfer, and BUFFER is a pointer
to somewhere in your virtual address space (such as memory obtained
from `malloc') where the data will go.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     unsigned short shift_state;
     _dosmemgetb(0x417, 2, &shift_state);
     if (shift_state & 0x0004)
       /* Ctrl key pressed */;


File: libc.info,  Node: dosmemgetl,  Next: dosmemgetw,  Prev: dosmemgetb,  Up: Alphabetical List

dosmemgetl
==========

Syntax
------

     #include <sys/movedata.h>

     void _dosmemgetl(unsigned long offset, size_t xfers, void *buffer);

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 OFFSET is a physical address, which can be computed
from a real-mode segment/offset pair as follows:

     offset = segment * 16 + offset;

The COUNT is the number of long-words to transfer, and BUFFER is a
pointer to somewhere in your virtual address space (such as memory
obtained from `malloc') where the data will go.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     unsigned long shift_state;
     _dosmemgetl(0x417, 1, &shift_state);
     if (shift_state & 0x0004)
       /* Ctrl key pressed */;


File: libc.info,  Node: dosmemgetw,  Next: dosmemput,  Prev: dosmemgetl,  Up: Alphabetical List

dosmemgetw
==========

Syntax
------

     #include <sys/movedata.h>

     void _dosmemgetw(unsigned long offset, size_t xfers, void *buffer);

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 OFFSET is a physical address, which can be computed
from a real-mode segment/offset pair as follows:

     offset = segment * 16 + offset;

The XFERS is the number of words to transfer, and BUFFER is a pointer
to somewhere in your virtual address space (such as memory obtained
from `malloc') where the data will go.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     unsigned short shift_state;
     _dosmemgetw(0x417, 1, &shift_state);
     if (shift_state & 0x0004)
       /* Ctrl key pressed */;


File: libc.info,  Node: dosmemput,  Next: dosmemputb,  Prev: dosmemgetw,  Up: Alphabetical List

dosmemput
=========

Syntax
------

     #include <sys/movedata.h>

     void dosmemput(const void *buffer, int length, int offset);

Description
-----------

This function transfers data from the program's virtual address space to
MS-DOS's conventional memory space.  The OFFSET is a physical address,
which can be computed from a real-mode segment/offset pair as follows:

     offset = segment * 16 + offset;

The LENGTH is the number of bytes to transfer, and BUFFER is a pointer
to somewhere in your virtual address space (such as memory obtained
from `malloc') where the data will come from.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     unsigned short save_screen[25][80];
     dosmemput(save_screen, 80*2*25, 0xb8000);


File: libc.info,  Node: dosmemputb,  Next: dosmemputl,  Prev: dosmemput,  Up: Alphabetical List

dosmemputb
==========

Syntax
------

     #include <sys/movedata.h>

     void _dosmemputb(const void *buffer, size_t xfers,
                      unsigned long offset);

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 OFFSET is a physical address, which can be computed
from a real-mode segment/offset pair as follows:

     offset = segment * 16 + offset;

The XFERS is the number of bytes to transfer, and BUFFER is a pointer
to somewhere in your virtual address space (such as memory obtained
from `malloc') where the data will come from.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     unsigned short save_screen[25][80];
     _dosmemputb(save_screen, 0xb8000, 80*2*25);


File: libc.info,  Node: dosmemputl,  Next: dosmemputw,  Prev: dosmemputb,  Up: Alphabetical List

dosmemputl
==========

Syntax
------

     #include <sys/movedata.h>

     void _dosmemputl(const void *buffer, size_t xfers,
                      unsigned long offset);

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 OFFSET is a physical address, which can be computed
from a real-mode segment/offset pair as follows:

     offset = segment * 16 + offset;

The XFERS is the number of long-words to transfer, and BUFFER is a
pointer to somewhere in your virtual address space (such as memory
obtained from `malloc') where the data will come from.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     unsigned short save_screen[25][80];
     _dosmemputl(save_screen, 40*25, 0xb8000);


File: libc.info,  Node: dosmemputw,  Next: dostrerr,  Prev: dosmemputl,  Up: Alphabetical List

dosmemputw
==========

Syntax
------

     #include <sys/movedata.h>

     void _dosmemputw(const void *buffer, size_t xfers,
                      unsigned long offset);

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 OFFSET is a physical address, which can be computed
from a real-mode segment/offset pair as follows:

     offset = segment * 16 + offset;

The XFERS is the number of short-words to transfer, and BUFFER is a
pointer to somewhere in your virtual address space (such as memory
obtained from `malloc') where the data will come from.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     unsigned short save_screen[25][80];
     _dosmemputw(save_screen, 0xb8000, 80*25);


File: libc.info,  Node: dostrerr,  Next: DPMI Overview,  Prev: dosmemputw,  Up: Alphabetical List

dostrerr
========

Syntax
------

     #include <dos.h>

     int dostrerr(struct DOSERROR *p_error, struct DOSERROR_str *p_str);

Description
-----------

This function accepts the extended error structure from DOS (e.g., from
the returned parameter from function `dosexterr', *note 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 `strerror' (*note strerror::), and can be
used to print descriptive messages corresponding to the errors
described in the `DOSERROR' structure.

For a list of the strings returned for each error number and type, see
*Note dosexterr::.

P_ERROR must point to the following structure:

     struct DOSERROR {
       int  exterror;
       char class;
       char action;
       char locus;
     };

P_STR must point to the following structure:

     struct DOSERROR_STR {
       char *exterror_str;
       char *class_str;
       char *action_str;
       char *locus_str;
     };

Return Value
------------

If either pointer parameter is `NULL', returns -1 and sets `errno' to
EINVAL.  If both parameters are not `NULL', checks the value of each
member of the `DOSERROR' parameter P_ERROR.  If each value is within
the limits of valid error codes for that member, sets parameter 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 P_STR member to the string "Unknown error: " followed
by the decimal numeric value of the error code.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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;
     }


File: libc.info,  Node: DPMI Overview,  Next: DPMI Specification,  Prev: dostrerr,  Up: Alphabetical List

DPMI Overview
=============

     extern unsigned short __dpmi_error;

For most functions, the error returned from the DPMI server is stored
in this variable.

     typedef struct {
       unsigned short offset16;
       unsigned short segment;
     } __dpmi_raddr;

This structure is used to hold a real-mode address, which consists of a
segment:offset pair.

     typedef struct {
       unsigned long  offset32;
       unsigned short selector;
     } __dpmi_paddr;

This structure is used to hold a protected-mode address, which consists
of a selector:offset pair.

     typedef struct {
       unsigned long handle;			/* 0, 2 */
       unsigned long size; 	/* or count */	/* 4, 6 */
       unsigned long address;		/* 8, 10 */
     } __dpmi_meminfo;

This structure is used by many functions that need to refer to blocks
of 32-bit memory.  The `size' field doubles as a count for those
operations that want a count of something, or return a count.

     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;

This structure is used by functions that pass register information,
such as simulating real-mode calls.

     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;

This structure is used to return version information to the program.

     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;

This structure is used to return information about the state of virtual
memory in the system.

     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;

This is also used to return memory information, but by a different
function.

     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;

This structure is used to install TSR programs.

     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;

This structure is used to manipulate shared memory regions.


File: libc.info,  Node: DPMI Specification,  Next: __dpmi_allocate_dos_memory,  Prev: DPMI Overview,  Up: Alphabetical List

DPMI Specification
==================

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/.


File: libc.info,  Node: __dpmi_allocate_dos_memory,  Next: __dpmi_allocate_ldt_descriptors,  Prev: DPMI Specification,  Up: Alphabetical List

__dpmi_allocate_dos_memory
==========================

Syntax
------

     #include <dpmi.h>

     int __dpmi_allocate_dos_memory(int _paragraphs,
                                    int *_ret_selector_or_max);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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 _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.

Return Value
------------

-1 on error, else the segment [0000..FFFF].

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_allocate_ldt_descriptors,  Next: __dpmi_allocate_linear_memory,  Prev: __dpmi_allocate_dos_memory,  Up: Alphabetical List

__dpmi_allocate_ldt_descriptors
===============================

Syntax
------

     #include <dpmi.h>

     int __dpmi_allocate_ldt_descriptors(int count);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0000

Allocates COUNT descriptors.

Return Value
------------

-1 on error, else the first descriptor.  Use
`__dpmi_get_selector_increment_value' (*note
__dpmi_get_selector_increment_value::) to figure out the remaining
selectors.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     short sel = __dpmi_allocate_ldt_descriptors(1);


File: libc.info,  Node: __dpmi_allocate_linear_memory,  Next: __dpmi_allocate_memory,  Prev: __dpmi_allocate_ldt_descriptors,  Up: Alphabetical List

__dpmi_allocate_linear_memory
=============================

Syntax
------

     #include <dpmi.h>

     int __dpmi_allocate_linear_memory(__dpmi_meminfo *info, int commit);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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.  COMMIT is 1 for
committed pages, else they are uncommitted.  It returns a handle and
the actual address.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_allocate_memory,  Next: __dpmi_allocate_real_mode_callback,  Prev: __dpmi_allocate_linear_memory,  Up: Alphabetical List

__dpmi_allocate_memory
======================

Syntax
------

     #include <dpmi.h>

     int __dpmi_allocate_memory(__dpmi_meminfo *_info);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0501

This allocates virtual memory.  Fill in size, returns handle and
address.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_allocate_real_mode_callback,  Next: __dpmi_allocate_shared_memory,  Prev: __dpmi_allocate_memory,  Up: Alphabetical List

__dpmi_allocate_real_mode_callback
==================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_allocate_real_mode_callback(void (*_handler)(void),
                                            __dpmi_regs *_regs,
                                            __dpmi_raddr *_ret);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_allocate_shared_memory,  Next: __dpmi_allocate_specific_ldt_descriptor,  Prev: __dpmi_allocate_real_mode_callback,  Up: Alphabetical List

__dpmi_allocate_shared_memory
=============================

Syntax
------

     #include <dpmi.h>

     int __dpmi_allocate_shared_memory(__dpmi_shminfo *info);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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
`INFO->size_requested'.  The function fills the rest of the structure:
allocated length in `INFO->size', block handle in `INFO->handle',
linear address in `INFO->address', and the selector:offset of an ASCIIZ
block name (up to 128 bytes long) in `INFO->name_selector' and
`INFO->name_offset', respectively.

The access to the shared memory block can be serialized by calling the
`__dpmi_serialize_on_shared_memory' function (*note
__dpmi_serialize_on_shared_memory::).

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_allocate_specific_ldt_descriptor,  Next: __dpmi_clear_debug_watchpoint,  Prev: __dpmi_allocate_shared_memory,  Up: Alphabetical List

__dpmi_allocate_specific_ldt_descriptor
=======================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_allocate_specific_ldt_descriptor(int _selector);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x000d

This allocates the specific selector given.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_clear_debug_watchpoint,  Next: __dpmi_create_alias_descriptor,  Prev: __dpmi_allocate_specific_ldt_descriptor,  Up: Alphabetical List

__dpmi_clear_debug_watchpoint
=============================

Syntax
------

     #include <dpmi.h>

     int __dpmi_clear_debug_watchpoint(unsigned long _handle);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0b01

Clear a debug watchpoint.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_create_alias_descriptor,  Next: __dpmi_discard_page_contents,  Prev: __dpmi_clear_debug_watchpoint,  Up: Alphabetical List

__dpmi_create_alias_descriptor
==============================

Syntax
------

     #include <dpmi.h>

     int __dpmi_create_alias_descriptor(int _selector);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x000a

Create a new selector with the same parameters as the given one.

Return Value
------------

-1 on error, else the new selector.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_discard_page_contents,  Next: __dpmi_free_dos_memory,  Prev: __dpmi_create_alias_descriptor,  Up: Alphabetical List

__dpmi_discard_page_contents
============================

Syntax
------

     #include <dpmi.h>

     int __dpmi_discard_page_contents(__dpmi_meminfo *_info);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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).

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_free_dos_memory,  Next: __dpmi_free_ldt_descriptor,  Prev: __dpmi_discard_page_contents,  Up: Alphabetical List

__dpmi_free_dos_memory
======================

Syntax
------

     #include <dpmi.h>

     int __dpmi_free_dos_memory(int _selector);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0101

This function frees the dos memory allocated by *Note
__dpmi_allocate_dos_memory::.  Remember to pass the selector and not
the segment.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_free_ldt_descriptor,  Next: __dpmi_free_memory,  Prev: __dpmi_free_dos_memory,  Up: Alphabetical List

__dpmi_free_ldt_descriptor
==========================

Syntax
------

     #include <dpmi.h>

     int __dpmi_free_ldt_descriptor(int descriptor);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0001

This function frees a single descriptor, even if it was allocated as
one of many.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     __dpmi_free_ldt_descriptor(sel);


File: libc.info,  Node: __dpmi_free_memory,  Next: __dpmi_free_physical_address_mapping,  Prev: __dpmi_free_ldt_descriptor,  Up: Alphabetical List

__dpmi_free_memory
==================

Syntax
------

     #include <dpmi.h>

     int __dpmi_free_memory(unsigned long _handle);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0502

This frees a block of virtual memory.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_free_physical_address_mapping,  Next: __dpmi_free_real_mode_callback,  Prev: __dpmi_free_memory,  Up: Alphabetical List

__dpmi_free_physical_address_mapping
====================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_free_physical_address_mapping(__dpmi_meminfo *info);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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 *Note
__dpmi_physical_address_mapping::.  Fill in the linear address.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_free_real_mode_callback,  Next: __dpmi_free_serialization_on_shared_memory,  Prev: __dpmi_free_physical_address_mapping,  Up: Alphabetical List

__dpmi_free_real_mode_callback
==============================

Syntax
------

     #include <dpmi.h>

     int __dpmi_free_real_mode_callback(__dpmi_raddr *_addr);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0303

This function frees the real-mode callback address.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_free_serialization_on_shared_memory,  Next: __dpmi_free_shared_memory,  Prev: __dpmi_free_real_mode_callback,  Up: Alphabetical List

__dpmi_free_serialization_on_shared_memory
==========================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_free_serialization_on_shared_memory(unsigned long handle,
                                                    int flags);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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 HANDLE.  The bit-mapped variable FLAGS defines the
following bits:

bit 0
     If set, release shared serialization (as opposed to exclusive
     serialization).

bit 1
     If set, free pending serialization.

bits 2-15
     Reserved (should be zero).

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_free_shared_memory,  Next: __dpmi_get_and_disable_virtual_interrupt_state,  Prev: __dpmi_free_serialization_on_shared_memory,  Up: Alphabetical List

__dpmi_free_shared_memory
=========================

Syntax
------

     #include <dpmi.h>

     int __dpmi_free_shared_memory(unsigned long handle);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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
HANDLE.  The handle becomes invalid after this call.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_and_disable_virtual_interrupt_state,  Next: __dpmi_get_and_enable_virtual_interrupt_state,  Prev: __dpmi_free_shared_memory,  Up: Alphabetical List

__dpmi_get_and_disable_virtual_interrupt_state
==============================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_and_disable_virtual_interrupt_state(void);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0900

This function disables interrupts, and returns the previous setting.

Return Value
------------

The previous setting.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_and_enable_virtual_interrupt_state,  Next: __dpmi_get_and_set_virtual_interrupt_state,  Prev: __dpmi_get_and_disable_virtual_interrupt_state,  Up: Alphabetical List

__dpmi_get_and_enable_virtual_interrupt_state
=============================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_and_enable_virtual_interrupt_state(void);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0901

This function enables interrupts, and returns the previous setting.

Return Value
------------

The previous setting.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_and_set_virtual_interrupt_state,  Next: __dpmi_get_capabilities,  Prev: __dpmi_get_and_enable_virtual_interrupt_state,  Up: Alphabetical List

__dpmi_get_and_set_virtual_interrupt_state
==========================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_and_set_virtual_interrupt_state(int _old_state);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AH = 0x09

This function restores the interrupt state from a previous call to
`__dpmi_get_and_disable_virtual_interrupt_state' (*note
__dpmi_get_and_disable_virtual_interrupt_state::) or
`__dpmi_get_and_enable_virtual_interrupt_state' (*note
__dpmi_get_and_enable_virtual_interrupt_state::).

Return Value
------------

The previous setting.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_capabilities,  Next: __dpmi_get_coprocessor_status,  Prev: __dpmi_get_and_set_virtual_interrupt_state,  Up: Alphabetical List

__dpmi_get_capabilities
=======================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_capabilities(int *flags, char *vendor_info);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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.  FLAGS are as follows:

     ---- ---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

The vendor info is a 128-byte buffer:

     [0] host major number
     [1] host minor number
     [2..127] vendor name

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_coprocessor_status,  Next: __dpmi_get_descriptor,  Prev: __dpmi_get_capabilities,  Up: Alphabetical List

__dpmi_get_coprocessor_status
=============================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_coprocessor_status(void);

Description
-----------

Please refer to *Note DPMI Specification::, for details on DPMI
function call operation.  Also see *Note DPMI Overview::, for general
information.

DPMI function AX = 0x0e00 (DPMI 1.0 only).  Not supported by CWSDPMI and
Windows.

Return Value
------------

-1 on error, else returns the processor status flags.  Here's the
meaning of each set bit:

bit 0
     If set, co-processor is enabled.  If reset, co-processor is
     disabled.

bit 1
     If set, the application is emulating the co-processor.

bit 2
     If set, the numeric co-processor is present.

bit 3
     If set, the DPMI host is emulating the co-processor.

bits 4-7
     The co-processor type:

    `0000'
          none

    `0010'
          80287

    `0011'
          80387

    `0100'
          80486 with a numeric processor


Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_descriptor,  Next: __dpmi_get_descriptor_access_rights,  Prev: __dpmi_get_coprocessor_status,  Up: Alphabetical List

__dpmi_get_descriptor
=====================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_descriptor(int _selector, void *_buffer);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x000b

This function fills the 8-byte buffer pointed to by _BUFFER with the
parameters of the descriptor whose selector is passed in _SELECTOR.
The data has the following format:

     [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]

Here's an alternative view of the layout that treats the buffer as an
array of 4 16-bit words (i.e., `unsigned short's):

     [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]

Special considerations apply to some of the fields:

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 "GPF", the General Protection Fault exception.

     For expand-down data segments (see below), the segment limit is the
     _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 _less_ than the segment limit result in a GPF.

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.

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:

          ---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

     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 (*note 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 (*note DPMI Specification::) requires this bit
     to be 0 for code segments.

     For data segments, the meaning of the `type' field is as follows:

          ---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

     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.

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.

Available bit
     This bit is left for the application's use.  It is neither set nor
     cleared by the DPMI server.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_descriptor_access_rights,  Next: __dpmi_get_extended_exception_handler_vector_pm,  Prev: __dpmi_get_descriptor,  Up: Alphabetical List

__dpmi_get_descriptor_access_rights
===================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_descriptor_access_rights(int _selector);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

This function returns the access rights byte from the `lar' opcode.

Return Value
------------

The access byte.  *Note __dpmi_set_descriptor_access_rights::, for the
details about the access information returned.  Also see *Note
__dpmi_get_descriptor::.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_extended_exception_handler_vector_pm,  Next: __dpmi_get_extended_exception_handler_vector_rm,  Prev: __dpmi_get_descriptor_access_rights,  Up: Alphabetical List

__dpmi_get_extended_exception_handler_vector_pm
===============================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_extended_exception_handler_vector_pm(
             int vector, __dpmi_paddr *address
     );

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_extended_exception_handler_vector_rm,  Next: __dpmi_get_free_memory_information,  Prev: __dpmi_get_extended_exception_handler_vector_pm,  Up: Alphabetical List

__dpmi_get_extended_exception_handler_vector_rm
===============================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_extended_exception_handler_vector_rm(
             int vector, __dpmi_paddr *address
     );

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_free_memory_information,  Next: __dpmi_get_memory_block_size_and_base,  Prev: __dpmi_get_extended_exception_handler_vector_rm,  Up: Alphabetical List

__dpmi_get_free_memory_information
==================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_free_memory_information(__dpmi_free_mem_info *_info);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0500

This function returns information about available memory.  Unsupported
fields will have -1 (0xfffffff) in them.

Return Value
------------

Zero.  This always works.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_memory_block_size_and_base,  Next: __dpmi_get_memory_information,  Prev: __dpmi_get_free_memory_information,  Up: Alphabetical List

__dpmi_get_memory_block_size_and_base
=====================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_memory_block_size_and_base(__dpmi_meminfo *info);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_memory_information,  Next: __dpmi_get_multiple_descriptors,  Prev: __dpmi_get_memory_block_size_and_base,  Up: Alphabetical List

__dpmi_get_memory_information
=============================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_memory_information(__dpmi_memory_info *buffer);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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:

`total_allocated_bytes_of_physical_memory_host'
     The total amount of allocated physical memory controlled by the
     DPMI host.

`total_allocated_bytes_of_virtual_memory_host'
     The total amount of allocated virtual memory controlled by the DPMI
     host.

`total_available_bytes_of_virtual_memory_host'
     The total amount of available virtual memory controlled by the DPMI
     host.

`total_allocated_bytes_of_virtual_memory_vcpu'
     The amount of virtual memory allocated by the DPMI host for the
     current virtual machine.

`total_available_bytes_of_virtual_memory_vcpu'
     The amount of virtual memory available for the current virtual
     machine.

`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).

`total_available_bytes_of_virtual_memory_client'
     The amount of virtual memory available to the current client.

`total_locked_bytes_of_memory_client'
     The amount of memory locked by the calling program.

`max_locked_bytes_of_memory_client'
     Maximum locked memory for the current client.

`highest_linear_address_available_to_client'
     The highest linear address available to the calling program.

`size_in_bytes_of_largest_free_memory_block'
     Size of the largest available memory block.

`size_of_minimum_allocation_unit_in_bytes'
     Size of the smallest block that can be allocated.

`size_of_allocation_alignment_unit_in_bytes'
     The alignment of allocated memory blocks.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_multiple_descriptors,  Next: __dpmi_get_page_attributes,  Prev: __dpmi_get_memory_information,  Up: Alphabetical List

__dpmi_get_multiple_descriptors
===============================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_multiple_descriptors(int count, void *buffer);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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 BUFFER must be prefilled with selector values, and will contain
the parameters on return:

     [0x00:2] selector #1 (pass)
     [0x02:8] parameters #1 (returned)
     [0x0a:2] selector #2 (pass)
     [0x0c:8] parameters #2 (returned)
     ...

Return Value
------------

Returns COUNT if successful, the negative of the number of descriptors
copied if failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_page_attributes,  Next: __dpmi_get_page_size,  Prev: __dpmi_get_multiple_descriptors,  Up: Alphabetical List

__dpmi_get_page_attributes
==========================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_page_attributes(__dpmi_meminfo *info, short *buffer);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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 `INFO->handle', offset of first page (relative to start of
block) in `INFO->address', and number of pages in `INFO->count'.  The
buffer BUFFER gets filled in with the attributes.  For each page, a
16-bit attribute word in BUFFER defines the attributes of that page as
follows:

bits 0-2
     Page type:

    `000'
          uncommitted

    `001'
          committed

    `010'
          mapped

bit 3
     If set, the page is read/write.  If cleared, the page is read-only.

bit 4
     If set, bits 5 and 6 specify accessed and dirty bits.

bit 5
     The page has been accessed (only valid if bit 4 is set).

bit 6
     The page has been written (is "dirty").  Only valid if bit 4 is
     set.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_page_size,  Next: __dpmi_get_processor_exception_handler_vector,  Prev: __dpmi_get_page_attributes,  Up: Alphabetical List

__dpmi_get_page_size
====================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_page_size(unsigned long *_size);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0604

Fills in the page size.

Return Value
------------

-1 on error (16-bit host), else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_processor_exception_handler_vector,  Next: __dpmi_get_protected_mode_interrupt_vector,  Prev: __dpmi_get_page_size,  Up: Alphabetical List

__dpmi_get_processor_exception_handler_vector
=============================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_processor_exception_handler_vector(
             int _vector, __dpmi_paddr *_address
     );

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0202

This function gets the current protected-mode exception handler (not
interrupts) for the exception _VECTOR.  It will return a
selector:offset pair in the members of the _ADDRESS variable.

Return Value
------------

-1 on error (invalid vector), else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_protected_mode_interrupt_vector,  Next: __dpmi_get_raw_mode_switch_addr,  Prev: __dpmi_get_processor_exception_handler_vector,  Up: Alphabetical List

__dpmi_get_protected_mode_interrupt_vector
==========================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_protected_mode_interrupt_vector(int _vector,
                                                    __dpmi_paddr *_address);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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.

Return Value
------------

Zero.  This always works.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_raw_mode_switch_addr,  Next: __dpmi_get_real_mode_interrupt_vector,  Prev: __dpmi_get_protected_mode_interrupt_vector,  Up: Alphabetical List

__dpmi_get_raw_mode_switch_addr
===============================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_raw_mode_switch_addr(__dpmi_raddr *_rm,
                                         __dpmi_paddr *_pm);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0306

Read the spec for more info.

Return Value
------------

Zero.  This always works.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_real_mode_interrupt_vector,  Next: __dpmi_get_segment_base_address,  Prev: __dpmi_get_raw_mode_switch_addr,  Up: Alphabetical List

__dpmi_get_real_mode_interrupt_vector
=====================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_real_mode_interrupt_vector(int _vector,
                                               __dpmi_raddr *_address);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0200

This function stores the real-mode interrupt vector address in
_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.

Return Value
------------

Zero.  This function always works.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_segment_base_address,  Next: __dpmi_get_segment_limit,  Prev: __dpmi_get_real_mode_interrupt_vector,  Up: Alphabetical List

__dpmi_get_segment_base_address
===============================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_segment_base_address(int _selector,
                                         unsigned long *_addr);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0006

The physical base address of the selector is stored in *ADDR.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     unsigned long addr;
     if (__dpmi_get_segment_base_address(selector, &addr))
       ...


File: libc.info,  Node: __dpmi_get_segment_limit,  Next: __dpmi_get_selector_increment_value,  Prev: __dpmi_get_segment_base_address,  Up: Alphabetical List

__dpmi_get_segment_limit
========================

Syntax
------

     #include <dpmi.h>

     unsigned __dpmi_get_segment_limit(int _selector);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

Return Value
------------

The limit of the segment, as returned by the `lsl' opcode.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_selector_increment_value,  Next: __dpmi_get_state_of_debug_watchpoint,  Prev: __dpmi_get_segment_limit,  Up: Alphabetical List

__dpmi_get_selector_increment_value
===================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_selector_increment_value(void);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0003

Return Value
------------

The value to add to each selector allocated by
__dpmi_allocate_ldt_descriptors to get the next one.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_state_of_debug_watchpoint,  Next: __dpmi_get_state_save_restore_addr,  Prev: __dpmi_get_selector_increment_value,  Up: Alphabetical List

__dpmi_get_state_of_debug_watchpoint
====================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_state_of_debug_watchpoint(unsigned long _handle,
                                              int *_status);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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).

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_state_save_restore_addr,  Next: __dpmi_get_vendor_specific_api_entry_point,  Prev: __dpmi_get_state_of_debug_watchpoint,  Up: Alphabetical List

__dpmi_get_state_save_restore_addr
==================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_state_save_restore_addr(__dpmi_raddr *_rm,
                                            __dpmi_paddr *_pm);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0305

Read the spec for info.

Return Value
------------

The number of bytes required to save state.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_vendor_specific_api_entry_point,  Next: __dpmi_get_version,  Prev: __dpmi_get_state_save_restore_addr,  Up: Alphabetical List

__dpmi_get_vendor_specific_api_entry_point
==========================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_vendor_specific_api_entry_point(char *_id,
                                                    __dpmi_paddr *_api);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0a00

Look up a vendor-specific function, given the _name_ of the function.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_version,  Next: __dpmi_get_virtual_interrupt_state,  Prev: __dpmi_get_vendor_specific_api_entry_point,  Up: Alphabetical List

__dpmi_get_version
==================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_version(__dpmi_version_ret *_ret);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0400

Fills in version information.  The flags are as follows:

     ---- ---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

The cpu is 2=80286, 3=80386, 4=80486, etc.

DPMI 0.9 returns major=0 and minor=0x5a.

Return Value
------------

Zero.  This always works.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_get_virtual_interrupt_state,  Next: __dpmi_install_resident_service_provider_callback,  Prev: __dpmi_get_version,  Up: Alphabetical List

__dpmi_get_virtual_interrupt_state
==================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_get_virtual_interrupt_state(void);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0902

Return Value
------------

This function returns the current interrupt flag (1=enabled).

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_install_resident_service_provider_callback,  Next: __dpmi_int,  Prev: __dpmi_get_virtual_interrupt_state,  Up: Alphabetical List

__dpmi_install_resident_service_provider_callback
=================================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_install_resident_service_provider_callback(
             __dpmi_callback_info *info
     );

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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 `__dpmi_terminate_and_stay_resident' (*note
__dpmi_terminate_and_stay_resident::).

The various members of INFO should be filled as follows:

`data16'
     An 8-byte descriptor for the 16-bit data segment.

`code16'
     An 8-byte descriptor for the 16-bit code segment (zeros if not
     supported).

`ip'
     A 16-bit offset of the 16-bit callback procedure.

`data32'
     An 8-byte descriptor for 32-bit data segment.

`code32'
     An 8-byte descriptor for 32-bit code segment (zeros if not
     supported).

`eip'
     A 32-bit offset of the 32-bit callback procedure.

*Note __dpmi_get_descriptor::, for the details about the layout of the
8-byte segment descriptor.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_int,  Next: __dpmi_lock_linear_region,  Prev: __dpmi_install_resident_service_provider_callback,  Up: Alphabetical List

__dpmi_int
==========

Syntax
------

     #include <dpmi.h>

     int __dpmi_int(int _vector, __dpmi_regs *_regs);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0300

This function performs a software interrupt in real mode after filling
in _most_ the registers from the given structure.  %ss, %esp, and
%eflags are automatically taken care of, unlike *Note
__dpmi_simulate_real_mode_interrupt::.

The following variables can be used to tune this function.  By default,
these variables are all zero.

`__dpmi_int_ss'
`__dpmi_int_sp'
`__dpmi_int_flags'
     These hold the values stored in the appropriate field in the
     `__dpmi_regs' structure.


Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_lock_linear_region,  Next: __dpmi_map_conventional_memory_in_memory_block,  Prev: __dpmi_int,  Up: Alphabetical List

__dpmi_lock_linear_region
=========================

Syntax
------

     #include <dpmi.h>

     int __dpmi_lock_linear_region(__dpmi_meminfo *_info);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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).

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_map_conventional_memory_in_memory_block,  Next: __dpmi_map_device_in_memory_block,  Prev: __dpmi_lock_linear_region,  Up: Alphabetical List

__dpmi_map_conventional_memory_in_memory_block
==============================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_map_conventional_memory_in_memory_block(
             __dpmi_meminfo *info, unsigned long physaddr
     );

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_map_device_in_memory_block,  Next: __dpmi_mark_page_as_demand_paging_candidate,  Prev: __dpmi_map_conventional_memory_in_memory_block,  Up: Alphabetical List

__dpmi_map_device_in_memory_block
=================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_map_device_in_memory_block(__dpmi_meminfo *info,
                                           unsigned long *physaddr);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_mark_page_as_demand_paging_candidate,  Next: __dpmi_mark_real_mode_region_as_pageable,  Prev: __dpmi_map_device_in_memory_block,  Up: Alphabetical List

__dpmi_mark_page_as_demand_paging_candidate
===========================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_mark_page_as_demand_paging_candidate(__dpmi_meminfo *_info);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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).

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_mark_real_mode_region_as_pageable,  Next: __dpmi_physical_address_mapping,  Prev: __dpmi_mark_page_as_demand_paging_candidate,  Up: Alphabetical List

__dpmi_mark_real_mode_region_as_pageable
========================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_mark_real_mode_region_as_pageable(__dpmi_meminfo *_info);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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).

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_physical_address_mapping,  Next: __dpmi_relock_real_mode_region,  Prev: __dpmi_mark_real_mode_region_as_pageable,  Up: Alphabetical List

__dpmi_physical_address_mapping
===============================

Syntax
------

     #include <dpmi.h>

     int __dpmi_physical_address_mapping(__dpmi_meminfo *_info);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_relock_real_mode_region,  Next: __dpmi_reset_debug_watchpoint,  Prev: __dpmi_physical_address_mapping,  Up: Alphabetical List

__dpmi_relock_real_mode_region
==============================

Syntax
------

     #include <dpmi.h>

     int __dpmi_relock_real_mode_region(__dpmi_meminfo *_info);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0603

This function relocks the pages unlocked with *Note
__dpmi_mark_real_mode_region_as_pageable::.  Pass address and size (in
bytes).

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_reset_debug_watchpoint,  Next: __dpmi_resize_dos_memory,  Prev: __dpmi_relock_real_mode_region,  Up: Alphabetical List

__dpmi_reset_debug_watchpoint
=============================

Syntax
------

     #include <dpmi.h>

     int __dpmi_reset_debug_watchpoint(unsigned long _handle);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0b03

Resets a watchpoint given its handle in _HANDLE.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_resize_dos_memory,  Next: __dpmi_resize_linear_memory,  Prev: __dpmi_reset_debug_watchpoint,  Up: Alphabetical List

__dpmi_resize_dos_memory
========================

Syntax
------

     #include <dpmi.h>

     int __dpmi_resize_dos_memory(int _selector, int _newpara,
                                  int *_ret_max);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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, _RET_MAX contains
the largest number of paragraphs available.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_resize_linear_memory,  Next: __dpmi_resize_memory,  Prev: __dpmi_resize_dos_memory,  Up: Alphabetical List

__dpmi_resize_linear_memory
===========================

Syntax
------

     #include <dpmi.h>

     int __dpmi_resize_linear_memory(__dpmi_meminfo *info, int commit);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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 COMMIT is 1 for committed pages; bit 1 is 1 to automatically
update descriptors.  It returns a new handle and base address.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_resize_memory,  Next: __dpmi_segment_to_descriptor,  Prev: __dpmi_resize_linear_memory,  Up: Alphabetical List

__dpmi_resize_memory
====================

Syntax
------

     #include <dpmi.h>

     int __dpmi_resize_memory(__dpmi_meminfo *_info);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_segment_to_descriptor,  Next: __dpmi_serialize_on_shared_memory,  Prev: __dpmi_resize_memory,  Up: Alphabetical List

__dpmi_segment_to_descriptor
============================

Syntax
------

     #include <dpmi.h>

     int __dpmi_segment_to_descriptor(int _segment);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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.

Return Value
------------

-1 on error, else the selector.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     short video = __dpmi_segment_to_descriptor(0xa000);
     movedata(_my_ds(), buffer, video, 0, 320*200);


File: libc.info,  Node: __dpmi_serialize_on_shared_memory,  Next: __dpmi_set_coprocessor_emulation,  Prev: __dpmi_segment_to_descriptor,  Up: Alphabetical List

__dpmi_serialize_on_shared_memory
=================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_serialize_on_shared_memory(unsigned long handle, int flags);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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 HANDLE.  The bit-mapped variable FLAGS defines the following
bits:

bit 0
     If set, return immediately if serialization is unavailable.  If
     cleared, the program is suspended until the serialization becomes
     available.

bit 1
     If set, perform shared serialization.  If cleared, perform
     exclusive serialization.

bits 2-15
     Reserved (should be zero).

An "exclusive serialization" blocks _any_ serialization attempts for
the same memory block from other virtual machines.  A "shared
serialization" blocks only _exclusive_ serialization attempts from
other virtual machines.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_set_coprocessor_emulation,  Next: __dpmi_set_debug_watchpoint,  Prev: __dpmi_serialize_on_shared_memory,  Up: Alphabetical List

__dpmi_set_coprocessor_emulation
================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_set_coprocessor_emulation(int flags);

Description
-----------

Please refer to *Note DPMI Specification::, for details on DPMI
function call operation.  Also see *Note DPMI Overview::, for general
information.

DPMI function AX = 0x0e01 (DPMI v1.0 only, but supported by most
DPMI v0.9 servers, including CWSDPMI, Windows, and QDPMI).

This function sets the co-processor emulation state as specified by
FLAGS.  The only two used bits in FLAGS are:

`bit 0'
     If set, enable the co-processor.  If reset, disable the
     co-processor.

`bit 1'
     If set, the emulation of the floating-point instructions will be
     done by the calling application.

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.)

Return Value
------------

-1 on errors, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_set_debug_watchpoint,  Next: __dpmi_set_descriptor,  Prev: __dpmi_set_coprocessor_emulation,  Up: Alphabetical List

__dpmi_set_debug_watchpoint
===========================

Syntax
------

     #include <dpmi.h>

     int __dpmi_set_debug_watchpoint(__dpmi_meminfo *_info, int _type);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_set_descriptor,  Next: __dpmi_set_descriptor_access_rights,  Prev: __dpmi_set_debug_watchpoint,  Up: Alphabetical List

__dpmi_set_descriptor
=====================

Syntax
------

     #include <dpmi.h>

     int __dpmi_set_descriptor(int _selector, void *_buffer);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x000c

This function sets the parameters of the selector _SELECTOR by copying
the contents of the 8-byte buffer pointed to by _BUFFER into the LDT
entry of the selector's descriptor.  *Note __dpmi_get_descriptor::, for
the description of the contents of the 8-byte buffer.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_set_descriptor_access_rights,  Next: __dpmi_set_extended_exception_handler_vector_pm,  Prev: __dpmi_set_descriptor,  Up: Alphabetical List

__dpmi_set_descriptor_access_rights
===================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_set_descriptor_access_rights(int _selector, int _rights);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0009

This sets the access rights of _SELECTOR to _RIGHTS.

The meaning of the individual bit fields of _RIGHTS is described below.
For more details, please refer to *Note __dpmi_get_descriptor::.

     ---- ---- ---- ---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)

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_set_extended_exception_handler_vector_pm,  Next: __dpmi_set_extended_exception_handler_vector_rm,  Prev: __dpmi_set_descriptor_access_rights,  Up: Alphabetical List

__dpmi_set_extended_exception_handler_vector_pm
===============================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_set_extended_exception_handler_vector_pm(
             int vector, __dpmi_paddr *address
     );

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_set_extended_exception_handler_vector_rm,  Next: __dpmi_set_multiple_descriptors,  Prev: __dpmi_set_extended_exception_handler_vector_pm,  Up: Alphabetical List

__dpmi_set_extended_exception_handler_vector_rm
===============================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_set_extended_exception_handler_vector_rm(
             int vector, __dpmi_paddr *address
     );

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_set_multiple_descriptors,  Next: __dpmi_set_page_attributes,  Prev: __dpmi_set_extended_exception_handler_vector_rm,  Up: Alphabetical List

__dpmi_set_multiple_descriptors
===============================

Syntax
------

     #include <dpmi.h>

     int __dpmi_set_multiple_descriptors(int count, void *buffer);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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
`__dpmi_get_multiple_descriptors' (*note
__dpmi_get_multiple_descriptors::), but the caller fills in everything
before calling.

Return Value
------------

Returns COUNT if successful, the negative of the number of descriptors
set if failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_set_page_attributes,  Next: __dpmi_set_processor_exception_handler_vector,  Prev: __dpmi_set_multiple_descriptors,  Up: Alphabetical List

__dpmi_set_page_attributes
==========================

Syntax
------

     #include <dpmi.h>

     int __dpmi_set_page_attributes(__dpmi_meminfo *info, short *buffer);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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
`INFO->handle', offset within block in `INFO->address', and number of
pages in `INFO->count'.  BUFFER points to an array of 16-bit words
which specify the new attributes.  *Note __dpmi_get_page_attributes::,
for the definition of the page attribute word.

The DJGPP startup code calls this function to uncommit the so-called
"null page", the first 4KB of the program's address space.  This causes
`NULL' pointer dereferences, a frequent programmatic error, to trigger
a Page Fault exception, rather than go unnoticed.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_set_processor_exception_handler_vector,  Next: __dpmi_set_protected_mode_interrupt_vector,  Prev: __dpmi_set_page_attributes,  Up: Alphabetical List

__dpmi_set_processor_exception_handler_vector
=============================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_set_processor_exception_handler_vector(
             int _vector, __dpmi_paddr *_address
     );

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_set_protected_mode_interrupt_vector,  Next: __dpmi_set_real_mode_interrupt_vector,  Prev: __dpmi_set_processor_exception_handler_vector,  Up: Alphabetical List

__dpmi_set_protected_mode_interrupt_vector
==========================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_set_protected_mode_interrupt_vector(int _vector,
                                                    __dpmi_paddr *_address);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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 `sti' before `iret' because `iret' won't always
restore interrupts in a virtual environment.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_set_real_mode_interrupt_vector,  Next: __dpmi_set_segment_base_address,  Prev: __dpmi_set_protected_mode_interrupt_vector,  Up: Alphabetical List

__dpmi_set_real_mode_interrupt_vector
=====================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_set_real_mode_interrupt_vector(int _vector,
                                               __dpmi_raddr *_address);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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.

Return Value
------------

Zero.  This function always works.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_set_segment_base_address,  Next: __dpmi_set_segment_limit,  Prev: __dpmi_set_real_mode_interrupt_vector,  Up: Alphabetical List

__dpmi_set_segment_base_address
===============================

Syntax
------

     #include <dpmi.h>

     int __dpmi_set_segment_base_address(int _selector, unsigned _address);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0007

This function sets the base address of the _SELECTOR to _ADDRESS.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_set_segment_limit,  Next: __dpmi_simulate_real_mode_interrupt,  Prev: __dpmi_set_segment_base_address,  Up: Alphabetical List

__dpmi_set_segment_limit
========================

Syntax
------

     #include <dpmi.h>

     int __dpmi_set_segment_limit(int _selector, unsigned _address);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0008

This function sets the highest valid address in the segment referenced
by _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.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_simulate_real_mode_interrupt,  Next: __dpmi_simulate_real_mode_procedure_iret,  Prev: __dpmi_set_segment_limit,  Up: Alphabetical List

__dpmi_simulate_real_mode_interrupt
===================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_simulate_real_mode_interrupt(int _vector,
                                             __dpmi_regs *_regs);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0300

This function performs a software interrupt in real mode after filling
in _all_ the registers from the given structure.  You _must_ set %ss,
%esp, and %eflags to valid real-mode values or zero, unlike *Note
__dpmi_int::.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_simulate_real_mode_procedure_iret,  Next: __dpmi_simulate_real_mode_procedure_retf,  Prev: __dpmi_simulate_real_mode_interrupt,  Up: Alphabetical List

__dpmi_simulate_real_mode_procedure_iret
========================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_simulate_real_mode_procedure_iret(__dpmi_regs *_regs);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0302

This function switches to real mode, filling in _all_ the registers
from the structure.  ss:sp and flags must be valid or zero.  The called
function must return with an `iret'.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_simulate_real_mode_procedure_retf,  Next: __dpmi_simulate_real_mode_procedure_retf_stack,  Prev: __dpmi_simulate_real_mode_procedure_iret,  Up: Alphabetical List

__dpmi_simulate_real_mode_procedure_retf
========================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_simulate_real_mode_procedure_retf(__dpmi_regs *_regs);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0301

This function switches to real mode with _all_ the registers set from
the structure, including cs:ip.  The function called should return with
a `retf'.  ss:sp and flags must be set to valid values or zero.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_simulate_real_mode_procedure_retf_stack,  Next: __dpmi_terminate_and_stay_resident,  Prev: __dpmi_simulate_real_mode_procedure_retf,  Up: Alphabetical List

__dpmi_simulate_real_mode_procedure_retf_stack
==============================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_simulate_real_mode_procedure_retf_stack(
             __dpmi_regs *_regs,
             int stack_words_to_copy, const void *stack_data
     );

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0301

This function switches to real mode with _all_ the registers set from
the structure, including cs:ip.  The function called should return with
a `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 STACK_WORDS_TO_COPY, and `NULL' for 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.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_terminate_and_stay_resident,  Next: __dpmi_unlock_linear_region,  Prev: __dpmi_simulate_real_mode_procedure_retf_stack,  Up: Alphabetical List

__dpmi_terminate_and_stay_resident
==================================

Syntax
------

     #include <dpmi.h>

     int __dpmi_terminate_and_stay_resident(int return_code,
                                            int paragraphs_to_keep);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note 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.  RETURN_CODE specifies which value to return to the OS.
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 *must* call the function
`__dpmi_install_resident_service_provider_callback' before this one,
otherwise it will be terminated instead of going TSR.  *Note
__dpmi_install_resident_service_provider_callback::.

Return Value
------------

This call does not return.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_unlock_linear_region,  Next: __dpmi_yield,  Prev: __dpmi_terminate_and_stay_resident,  Up: Alphabetical List

__dpmi_unlock_linear_region
===========================

Syntax
------

     #include <dpmi.h>

     int __dpmi_unlock_linear_region(__dpmi_meminfo *_info);

Description
-----------

Please refer to the DPMI Specification (*note DPMI Specification::) for
details on DPMI function call operation.  Also see the DPMI Overview
(*note DPMI Overview::) for general information.

DPMI function AX = 0x0601

This function unlocks virtual memory.  Pass address and size (in bytes).

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __dpmi_yield,  Next: dprintf,  Prev: __dpmi_unlock_linear_region,  Up: Alphabetical List

__dpmi_yield
============

Syntax
------

     #include <dpmi.h>

     void __dpmi_yield(void);

Description
-----------

`__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.

Return Value
------------

None.  If the call isn't supported by the environment, like when running
on plain DOS, `errno' is set to `ENOSYS'.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: dprintf,  Next: DTTOIF,  Prev: __dpmi_yield,  Up: Alphabetical List

dprintf
=======

Syntax
------

     #include <stdio.h>

     int dprintf(int file_desc, const char *format, ...);

Description
-----------

The function `dprintf' is an exact analog of `fprintf' (*note
fprintf::), except that it output to a file descriptor FILE_DESC
instead of to a stdio stream.

Return Value
------------

The number of characters written is returned; otherwise EOF is returned
to flag encoding or buffer space errors.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: DTTOIF,  Next: dup,  Prev: dprintf,  Up: Alphabetical List

DTTOIF
======

Syntax
------

     #include <dirent.h>

     struct dirent *de;
     mode_t file_mode = DTTOIF(de->d_type)

Description
-----------

This macro converts the `d_type' member of a `struct dirent' variable,
as returned by `readdir' (*note readdir::) to an equivalent value of
the `st_mode' member of a `struct stat' variable (*note stat::).

Note that the access rights are not set in the result returned by this
macro.  Only the file-type information is copied.

Return Value
------------

The file's mode bits are returned.  If the argument has the value
`DT_UNKNOWN', the result will be `S_IFREG'.

Portability
-----------

ANSI/ISO C   No
POSIX        No (see note 1)

Notes:

  1. This macro is available on systems which support the `d_type'
     member in `struct dirent'.


File: libc.info,  Node: dup,  Next: dup2,  Prev: DTTOIF,  Up: Alphabetical List

dup
===

Syntax
------

     #include <unistd.h>

     int dup(int old_handle);

Description
-----------

This function duplicates the given file handle.  Both handles refer to
the same file and file pointer.

Return Value
------------

The new file handle, or -1 if error.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     do_file(dup(fileno(stdin)));


File: libc.info,  Node: dup2,  Next: __dup_fd_properties,  Prev: dup,  Up: Alphabetical List

dup2
====

Syntax
------

     #include <unistd.h>

     int dup2(int existing_handle, int new_handle);

Description
-----------

This call causes NEW_HANDLE to refer to the same file and file pointer
as EXISTING_HANDLE.  If NEW_HANDLE is an open file, it is closed.

Return Value
------------

The new handle, or -1 on error.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     /* copy new file to stdin stream */
     close(0);
     dup2(new_stdin, 0);
     close(new_stdin);


File: libc.info,  Node: __dup_fd_properties,  Next: _dxe_load,  Prev: dup2,  Up: Alphabetical List

__dup_fd_properties
===================

Syntax
------

     #include <libc/fd_props.h>

     void __dup_fd_properties(int existing_handle, int new_handle);

Description
-----------

Causes the new file descriptor NEW_HANDLE to refer to the same
`fd_properties' struct as EXISTING_HANDLE.  This internal function is
called by `dup' and `dup2'.

For more information, see `__set_fd_properties' (*note
__set_fd_properties::) and `__clear_fd_properties' (*note
__clear_fd_properties::).

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _dxe_load,  Next: DXE_macros,  Prev: __dup_fd_properties,  Up: Alphabetical List

_dxe_load
=========

Syntax
------

     #include <sys/dxe.h>

     void *_dxe_load(char *dxe_filename);

Description
-----------

This function loads a dynamic executable image, whose file name is
pointed to by 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.

Return Value
------------

0 on failure, the address of the loaded symbol on success.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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));


File: libc.info,  Node: DXE_macros,  Next: ecvt,  Prev: _dxe_load,  Up: Alphabetical List

DXE_macros
==========

Syntax
------

     #include <sys/dxe.h>

     	DXE_EXPORT_TABLE(name)
     	DXE_EXPORT_TABLE_AUTO(name)
     	DXE_EXPORT(symbol)
     	DXE_EXPORT_ASM(_symbol)
     	DXE_EXPORT_END

Description
-----------

These macros allows you to define a table of symbols that are going to
be exported into subsequently loaded modules.  If you use
`DXE_EXPORT_TABLE_AUTO' instead of `DXE_EXPORT_TABLE' the table will be
automatically registered with the dynamic loader during program startup
(thus you don't need to call `dlregsym(name)' manually).

     	DXE_DEMAND(name);

This macro declares the two functions that are present if you are
statically linking against a dynamic library (see the `dxe3gen' section
for details on static linking).  Note that NAME should be in capitals
with any illegal character converted to underscore.  After declaring
the module with the above macro, you can call the `dlload_NAME' and
`dlunload_NAME' functions to dynamically load and unload the statically
linked dynamic library.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: ecvt,  Next: ecvtbuf,  Prev: DXE_macros,  Up: Alphabetical List

ecvt
====

Syntax
------

     #include <stdlib.h>

     char * ecvt (double value, int ndigits, int *decpt, int *sign)

Description
-----------

This function converts the VALUE into a null-terminated string, and
returns a pointer to that string.

`ecvt' works exactly like `ecvtbuf' (*note ecvtbuf::), except that it
generates the string in an internal static buffer which is overwritten
on each call.

Return Value
------------

A pointer to the generated string.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: ecvtbuf,  Next: edi_init,  Prev: ecvt,  Up: Alphabetical List

ecvtbuf
=======

Syntax
------

     #include <stdlib.h>

     char * ecvtbuf (double value, int ndigits, int *decpt, int *sign,
                     char *buf)

Description
-----------

This function converts its argument VALUE into a null-terminated string
of NDIGITS digits in BUF.  BUF should have enough space to hold at
least `NDIGITS + 1' characters.

The produced string in BUF does _not_ include the decimal point.
Instead, the position of the decimal point relative to the beginning of
BUF is stored in an integer variable whose address is passed in DECPT.
Thus, if BUF is returned as "1234" and *DECPT as 1, this corresponds to
a value of 1.234; if *DECPT is -1, this corresponds to a value of
0.01234, etc.

The sign is also not included in BUF's value.  If VALUE is negative,
`ecvtbuf' puts a nonzero value into the variable whose address is
passed in SIGN; otherwise it stores zero in *SIGN.

The least-significant digit in BUF is rounded.

`ecvtbuf' produces the string "NaN" if VALUE is a NaN, and "Inf" or
"Infinity" if VALUE is an infinity (the longer form is produced when
NDIGITS is 8 or more).

Return Value
------------

A pointer to BUF.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: edi_init,  Next: enable,  Prev: ecvtbuf,  Up: Alphabetical List

edi_init
========

Syntax
------

     #include <debug/dbgcom.h>

     void edi_init (jmp_buf start_state);

Description
-----------

This function is part of the DJGPP "debugging support".  It should be
called after a call to `v2loadimage' (*note v2loadimage::) which loads
an executable program as a debuggee.  `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 START_STATE is usually set by a preceding call to
`v2loadimage'.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

      if (v2loadimage (exec_file, cmdline, start_state))
        {
           printf ("Load failed for image %s\n", exec_file);
           exit (1);
        }

       edi_init (start_state);


File: libc.info,  Node: enable,  Next: endgrent,  Prev: edi_init,  Up: Alphabetical List

enable
======

Syntax
------

     #include <dos.h>

     int enable(void);

Description
-----------

This function enables interrupts.

*Note disable::.

Return Value
------------

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

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     int ints_were_enabled;

     ints_were_enabled = enable();
     . . . do some stuff . . .
     if (!ints_were_enabled)
       disable();


File: libc.info,  Node: endgrent,  Next: endmntent,  Prev: enable,  Up: Alphabetical List

endgrent
========

Syntax
------

     #include <grp.h>

     void endgrent(void);

Description
-----------

This function should be called after all calls to `getgrent',
`getgrgid', or `getgrnam'.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

*Note getgrent::.


File: libc.info,  Node: endmntent,  Next: endpwent,  Prev: endgrent,  Up: Alphabetical List

endmntent
=========

Syntax
------

     #include <mntent.h>

     int endmntent(FILE *filep);

Description
-----------

This function should be called after the last call to `getmntent'
(*note getmntent::).

Return Value
------------

This function always returns one.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: endpwent,  Next: errno,  Prev: endmntent,  Up: Alphabetical List

endpwent
========

Syntax
------

     #include <pwd.h>

     void endpwent(void);

Description
-----------

This function should be called after the last call to getpwent (*note
getpwent::).

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: errno,  Next: exec*,  Prev: endpwent,  Up: Alphabetical List

errno
=====

Syntax
------

     #include <errno.h>

     extern int errno;

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:

`0'
     No Error.  Library functions never set `errno' to zero, but the
     startup code does that just before calling `main' (this is ANSI C
     requirement).

`1'
     EDOM - Numerical input to a function is out of range.

`2'
     ERANGE - Numerical output of a function is out of range.

`3'
     E2BIG - Argument list too long.  `system' and the functions from
     the `spawn' family assign this to `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).

`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."

`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").

`6'
     EBADF - Bad file descriptor: an invalid file handle passed to a
     library function.

`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.

`8'
     ECHILD - No child processes.  Returned by `wait' and `waitpid',
     and by NetWare-related calls.

`9'
     EDEADLK - Resource deadlock avoided.  Never used in DJGPP.

`10'
     EEXIST - File exists.  Returned by `open' and `mkdir' when a file
     or directory by that name already exists.

`11'
     EFAULT - Bad address.  A function was passed a bad pointer (like a
     `NULL' pointer).

`12'
     EFBIG - File too large.  Never used in DJGPP.

`13'
     EINTR - Interrupted system call.  `system' and the functions of
     the `spawn' family use that when the child program was interrupted
     by `Ctrl-<C>'.  Also, when DOS returns the "fail on INT 24h" error
     code.

`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 `rename', syntax
     errors in the command line passed to `system', etc.

`15'
     EIO - Input or output error.  Low-level error in I/O operation,
     like bad disk block, damaged FAT, etc.

`16'
     EISDIR - Is a directory: an attempt to do something with a
     directory which is only allowed with regular files.  DOS usually
     returns `EACCES' in these cases, but DJGPP sometimes assigns
     `EISDIR' to `errno', like when `rename' is called to move a regular
     file over a directory, or when `system' or one of the `spawn*'
     functions are passed a name of a directory instead of an executable
     program.

`17'
     EMFILE - Too many open files in system (no more handles available).
     This usually means that the number specified by the `FILES='
     directive in `CONFIG.SYS' is too small.

`18'
     EMLINK - Too many links.  Not used in DJGPP (as DOS doesn't support
     hard links).

`19'
     ENAMETOOLONG - File name too long (longer than `FILENAME_MAX',
     defined in `stdio.h').

`20'
     ENFILE - Too many open files.  Never used in DJGPP.

`21'
     ENODEV - No such device.  Attempt to access an invalid drive, or an
     invalid operation for the type of drive.

`22'
     ENOENT - No such file or directory.

`23'
     ENOEXEC - Unable to execute file.  Returned by `_dxe_load' (when
     the argument names a file that isn't a valid DXE), and by
     NetWare-related calls which run programs remotely.

`24'
     ENOLCK - No locks available.  Returned when the DOS file-locking
     functions cannot lock more files (due to overflow of the sharing
     buffer).

`25'
     ENOMEM - Not enough memory.  Note that, unlike your expectations,
     `malloc' does NOT set `errno' to `ENOMEM'; however, several
     library functions that use `malloc' will do that when it returns a
     `NULL' pointer.

`26'
     ENOSPC - No space left on drive.  DOS usually doesn't return this
     error, but `write' and `_write' do this for it, when they detect a
     full disk condition.

`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.

`28'
     ENOTDIR - Not a directory.  DOS never returns this code, but some
     library functions, like `rename' and `_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.

`29'
     ENOTEMPTY - Directory not empty.  DOS never returns this code, but
     `rename' does, when it is called to move a directory over an
     existing non-empty directory.

`30'
     ENOTTY - Inappropriate I/O control operation.  The "termios"
     functions set `errno' to this when called on a device that is not a
     TTY.

`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.

`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.

`33'
     EPIPE - Broken pipe: attempt to write to a pipe with nobody to read
     it.  This never happens in DJGPP.

`34'
     EROFS - Read-only file system: attempt to write to a read-only
     disk.  Unfortunately, DOS almost never returns this code.

`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.

`36'
     ESRCH - No such process.  Not used in DJGPP.

`37'
     EXDEV - Improper link.  An attempt to rename a file across drives
     or create a cross-device hardlink.

`38'
     ENMFILE - No more files.  `findfirst' and `findnext' assign this
     to `errno' when they exhaust the files in the directory.
     `readdir' does that as well.

`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).

`40'
     EOVERFLOW - Value too large.  `filelength' can assign this to
     `errno' when a file's length is larger than 2^31-2 (*note
     filelength::).  `lfilelength' can assign this to `errno' when a
     file's length is larger than 2^63-1 (*note lfilelength::).

`41'
     EILSEQ - Invalid or incomplete multibyte or wide character.


*Note perror::.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: exec*,  Next: __exit,  Prev: errno,  Up: Alphabetical List

exec*
=====

Syntax
------

     #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[]);

Description
-----------

These functions operate by calling `spawn*' with a type of `P_OVERLAY'.
Refer to `spawn*' (*note spawn*::) for a full description.

Return Value
------------

If successful, these functions do not return.  If there is an error,
these functions return -1 and set `errno' to indicate the error.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     execlp("gcc", "gcc", "-v", "hello.c", 0);


File: libc.info,  Node: __exit,  Next: _exit,  Prev: exec*,  Up: Alphabetical List

__exit
======

Syntax
------

     #include <unistd.h>

     void __exit(int exit_code);

Description
-----------

This is an internal library function which exits the program, returning
EXIT_CODE to the calling process.  No additional processing is done,
and any `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 `_exit'; do _not_ call it directly.

Return Value
------------

This function does not return.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: _exit,  Next: _Exit,  Prev: __exit,  Up: Alphabetical List

_exit
=====

Syntax
------

     #include <unistd.h>

     void _exit(int exit_code);

Description
-----------

This function exits the program, returning 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 `atexit'
functions are not called; only the hardware interrupt handlers are
unhooked, to prevent system crashes e.g. after a call to `abort'.  This
function is normally called only by `exit' and `abort'.

Return Value
------------

This function does not return.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _Exit,  Next: exit,  Prev: _exit,  Up: Alphabetical List

_Exit
=====

Syntax
------

     #include <stdlib.h>

     void _Exit(int exit_code);

Description
-----------

This function exits the program, returning 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 `atexit'
functions are not called; only the hardware interrupt handlers are
unhooked, to prevent system crashes.

Return Value
------------

This function does not return.

Portability
-----------

ANSI/ISO C   C99 (see note 1); not C89
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992

Notes:

  1. Depending on the implementation, `_Exit' may do the additional
     processing described above.


Example
-------

     if (argc < 4)
     {
       print_usage();
       _Exit(1);
     }


File: libc.info,  Node: exit,  Next: exp,  Prev: _Exit,  Up: Alphabetical List

exit
====

Syntax
------

     #include <stdlib.h>

     void exit(int exit_code);

Description
-----------

This function exits the program, returning EXIT_CODE to the calling
process.  Before exiting, all open files are closed and all `atexit'
and `on_exit' requests are processed.

Return Value
------------

This function does not return.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     if (argc < 4)
     {
       print_usage();
       exit(1);
     }


File: libc.info,  Node: exp,  Next: exp10,  Prev: exit,  Up: Alphabetical List

exp
===

Syntax
------

     #include <math.h>

     double exp(double x);

Description
-----------

This function computes the exponential of X, e^x, where e is the base
of the natural system of logarithms, approximately 2.718281828.

Return Value
------------

e to the X power.  If the value of X is finite, but so large in
magnitude that its exponential cannot be accurately represented by a
`double', the return value is the nearest representable `double'
(possibly, an `Inf'), and `errno' is set to `ERANGE'.  If X is either a
positive or a negative infinity, the result is either `+Inf' or zero,
respectively, and `errno' is not changed.  If X is a `NaN', the return
value is `NaN' and `errno' is set to `EDOM'.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: exp10,  Next: exp2,  Prev: exp,  Up: Alphabetical List

exp10
=====

Syntax
------

     #include <math.h>

     double exp10(double x);

Description
-----------

This function computes 10 to the power of X, 10^x.

Return Value
------------

10 to the X power.  If the value of X is finite, but so large in
magnitude that 10^x cannot be accurately represented by a `double', the
return value is the nearest representable `double' (possibly, an
`Inf'), and `errno' is set to `ERANGE'.  If X is either a positive or a
negative infinity, the result is either `+Inf' or zero, respectively,
and `errno' is not changed.  If X is a `NaN', the return value is `NaN'
and `errno' is set to `EDOM'.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: exp2,  Next: expm1,  Prev: exp10,  Up: Alphabetical List

exp2
====

Syntax
------

     #include <math.h>

     double exp2(double x);

Description
-----------

This function computes 2 to the power of X, 2^x.

Return Value
------------

2 to the X power.  If the value of X is finite, but so large in
magnitude that 2^x cannot be accurately represented by a `double', the
return value is is the nearest representable `double' (possibly, an
`Inf'), and `errno' is set to `ERANGE'.  If X is either a positive or a
negative infinity, the result is either `+Inf' or zero, respectively,
and `errno' is not changed.  If X is a `NaN', the return value is `NaN'
and `errno' is set to `EDOM'.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: expm1,  Next: fabs,  Prev: exp2,  Up: Alphabetical List

expm1
=====

Syntax
------

     #include <math.h>

     double expm1(double x);

Description
-----------

This function computes the value of e^x - 1, the exponential of X minus
1, where e is the base of the natural system of logarithms,
approximately 2.718281828.  The result is more accurate than `exp(x) -
1' for small values of X, where the latter method would lose many
significant digits.

Return Value
------------

e raised to the power X, minus 1.  If the value of X is finite, but so
large that its exponent would overflow a `double', the return value is
`Inf', and `errno' is set to `ERANGE'.  If X is either a positive or a
negative infinity, the result is either `+Inf' or -1, respectively, and
`errno' is not changed.  If X is a `NaN', the return value is `NaN' and
`errno' is set to `EDOM'.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: fabs,  Next: _far*,  Prev: expm1,  Up: Alphabetical List

fabs
====

Syntax
------

     #include <math.h>

     double fabs(double x);

Description
-----------

This function computes the absolute value of its argument X.

Return Value
------------

X if X is positive, else -X.  Note that in this context, +0.0 is
positive and -0.0 is negative.  Infinities and `NaN's are returned
unchanged, except for the sign.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: _far*,  Next: fchdir,  Prev: fabs,  Up: Alphabetical List

_far*
=====

Syntax
------

     #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);

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 SELECTOR and an OFFSET.  This
selector is _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 VALUE to put there.

The last two groups assume that you've used `_farsetsel' to specify the
selector.  You should avoid making any function calls between
`_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 `_fargetsel' if you
want to temporary change the selector with `_farsetsel' and restore it
afterwards.

Return Value
------------

Functions which peek the address return the value at given address.
`_fargetsel' returns the current selector.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: fchdir,  Next: fchmod,  Prev: _far*,  Up: Alphabetical List

fchdir
======

Syntax
------

     #include <unistd.h>

     int fchdir(int fd);

Description
-----------

This function changes the current directory to the directory described
by the file descriptor FD.

Return Value
------------

Zero on success, else nonzero and ERRNO set if error.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     int fd;

     fd = open("dir", O_RDONLY);
     fchdir(fd);


File: libc.info,  Node: fchmod,  Next: fchown,  Prev: fchdir,  Up: Alphabetical List

fchmod
======

Syntax
------

     #include <sys/stat.h>

     int fchmod(int fd, mode_t mode);

Description
-----------

This function changes the mode (writable or write-only) of the file
opened under the file descriptor FD.  The value of MODE can be a
combination of one or more of the `S_I*' constants described in the
description of the `chmod' function (*note chmod::).

Some `S_I*' constants are ignored for regular files:

   * `S_I*GRP' and `S_I*OTH' are ignored, because DOS/Windows has no
     concept of ownership, so all files are considered to belong to the
     user;

   * `S_IR*' are ignored, because files are always readable on
     DOS/Windows.

`fchmod' will always succeed for character devices, but the mode will
be ignored.

`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 `fopen' (*note fopen::) and `open' (*note open::)
functions.  Low-level methods include the `_open' (*note _open::) and
`_dos_open' (*note _dos_open::) functions.  In particular, redirected
handles cannot have their mode changed with `fchmod'.

`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 `fchmod',
but then written to, then the mode will not be changed.

This function can be hooked by File System Extensions (*note File
System Extensions::).

Return Value
------------

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

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     int fd;

     fd = open("/tmp/dj.dat", O_RDWR);
     fchmod(fd, S_IWUSR|S_IRUSR);


File: libc.info,  Node: fchown,  Next: fclose,  Prev: fchmod,  Up: Alphabetical List

fchown
======

Syntax
------

     #include <unistd.h>

     int fchown(int fd, uid_t owner, gid_t group);

Description
-----------

This function changes the ownership of the open file specified by FD to
the user ID OWNER and group ID GROUP.

This function does almost nothing under MS-DOS: it just checks if the
handle `fd' is valid.  This function can be hooked by File System
Extensions (*note File System Extensions::).

Return Value
------------

This function returns zero if the handle is valid, non-zero otherwise.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: fclose,  Next: fcntl,  Prev: fchown,  Up: Alphabetical List

fclose
======

Syntax
------

     #include <stdio.h>

     int fclose(FILE *file);

Description
-----------

This function closes the given FILE.

Return Value
------------

Zero on success, else `EOF'.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     FILE *f = fopen("data", "r");
     fprintf(f, "Hello\n");
     fclose(f);


File: libc.info,  Node: fcntl,  Next: fcvt,  Prev: fclose,  Up: Alphabetical List

fcntl
=====

Syntax
------

     #include <fcntl.h>

     int fcntl (int fd, int cmd, ...);

Description
-----------

This function performs the operation specified by CMD on the file open
on handle FD.  The following operations are defined by the header
`fcntl.h':

`F_DUPFD'
     Returns a file handle that duplicates FD like `dup' does (*note
     dup::), except that `fcntl' also makes sure the returned handle is
     the lowest available handle greater than or equal to the integer
     value of the third argument.

`F_GETFD'
     Get the `FD_CLOEXEC' close-on-exec (a.k.a. no-inherit) status of
     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
     `FD_CLOEXEC' for handles 18 and above.

     For handles less than 18, the call will try to determine the
     status of the `O_NOINHERIT' flag for that file and will return
     either `FD_CLOEXEC' if the flag is set, or 0 if the flag is not
     set.  If the status of the `O_NOINHERIT' flag cannot be
     determined, the call will return -1, setting `errno' to `ENOSYS'.

     The no-inherit bit can be set when the file is opened by using the
     `O_NOINHERIT' in the open flags; see *Note open::.

`F_SETFD'
     Set or unset the close-on-exec flag for the handle 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 `errno' to `ENOSYS'.

     For handles less than 18, the call will try to set or unset the
     `O_NOINHERIT' flag for that file and will return 0 if the flag is
     changed.  If the `O_NOINHERIT' flag cannot be changed, the call
     will return -1, setting `errno' to `ENOSYS'.

`F_GETFL'
     Get the open mode and status flags associated with the handle FD.
     The flags are those supported by `open' and `creat' functions,
     like `O_RDONLY', `O_APPEND', etc.

     On Windows NT this cannot report the open mode correctly --
     `O_RDONLY' is always returned.

`F_SETFL'
     Set the open mode and status flags associated with the handle FD.
     This fails in all but one case, and sets `errno' to `ENOSYS',
     since DOS and Windows don't allow changing the descriptor flags
     after the file is open.

     The one allowed case is for `O_NONBLOCK', since DJGPP doesn't
     support it anyway.  That is, calls using `F_SETFL' will fail for
     all flag values *except* `O_NONBLOCK'.

          #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.               */

`F_GETLK'
     Return the lock structure that prevents obtaining the lock pointed
     to by the third argument, or set the `l_type' field of the lock
     structure to `F_UNLCK' if there is no obstruction.  Currently,
     only the setting of the `l_type' field is provided.  This call
     will not return values in the `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 `errno' is set to
     the reason (which will be one of `EINVAL', `EBADF', `EACCES' or
     `ENOLCK').

     Locking of directories is not supported.

`F_SETLK'
     Set or clear a file segment lock according to the structure
     pointed to by the third argument.  The lock is set when `l_type' is
     `F_RDLCK' (shared lock request) or `F_WRLCK' (exclusive lock
     request), and the lock is cleared when `l_type' is `F_UNLCK'.  If
     the lock is already held, then this call returns -1 and sets
     `errno' to `EACCES'.

     The `F_RDLCK' value for requesting a read lock is always treated as
     if it were `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.

`F_SETLKW'
     Same as `F_SETLK', but if the lock is blocked, the call will wait
     (using `__dpmi_yield', see *note __dpmi_yield::) until it is
     unblocked and the lock can be applied.  This call will *never
     exit* if the program making the call is the program which already
     owns the lock.

     Locking of directories is not supported.

`F_GETLK64'

`F_SETLK64'

`F_SETLKW64'
     Each of these does exactly the same function as the non-"64"
     version, but the third argument must be of type `struct flock64',
     which allows the L_START and L_LEN members to be `long long int'
     values.  The current code will only use these `long long int'
     values modulo 2^32, which allows file locking positions up to 4
     gigabytes minus 1.  True 64-bit file locking is *not* supported.

     The `struct flock64' members L_START and L_LEN are declared to be
     of type `offset_t', which is in turn typedef'ed to be a `long
     long'.

     Locking of directories is not supported.

This function can be hooked by the "Filesystem extensions", see *Note
File System Extensions::.  If you don't want this, and you are calling
`fcntl' with the `F_DUPFD' command, you should use `dup2' instead, see
*Note dup2::.

Return Value
------------

If an invalid or unsupported value is passed in CMD, or FD is an
invalid file handle, the function returns -1 and sets `errno' to the
appropriate value.  Unsupported values of CMD cause `ENOSYS' to be
stored in `errno'.  If CMD is `F_DUPFD', the function returns the new
descriptor or -1 in case of a failure.

Lock requests which specify the open file's current `EOF' position as
the value of L_START and zero as the L_LEN value will fail, returning
-1 with `errno' set to `EACCES'.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)

Notes:

  1. Contrary to Posix requirement, the handle returned by `F_DUPFD'
     shares the `FD_CLOEXEC' flag with 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 `open'.

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);


File: libc.info,  Node: fcvt,  Next: fcvtbuf,  Prev: fcntl,  Up: Alphabetical List

fcvt
====

Syntax
------

     #include <stdlib.h>

     char * fcvt (double value, int ndigits, int *decpt, int *sign)

Description
-----------

This function converts the VALUE into a null-terminated string, and
returns a pointer to that string.

`fcvt' works exactly like `fcvtbuf' (*note fcvtbuf::), except that it
generates the string in an internal static buffer which is overwritten
on each call.

Return Value
------------

A pointer to the generated string.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: fcvtbuf,  Next: fdopen,  Prev: fcvt,  Up: Alphabetical List

fcvtbuf
=======

Syntax
------

     #include <stdlib.h>

     char * fcvtbuf (double value, int ndigits, int *decpt, int *sign,
                     char *buf)

Description
-----------

This function converts its argument VALUE into a null-terminated string
in BUF with NDIGITS digits _to the right_ of the decimal point.
NDIGITS can be negative to indicate rounding to the left of the decimal
point.  BUF should have enough space to hold at least
`310+max(0,NDIGITS)' characters.

Note that, unlike `ecvtbuf' (*note ecvtbuf::), `fcvtbuf' only counts
the digits _to the right_ of the decimal point.  Thus, if VALUE is
123.45678 and NDIGITS is 4, then `ecvtbuf' will produce "1235", but
`fcvtbuf' will produce "1234568" (and *DECPT will be 3 in both cases).

The produced string in BUF does _not_ include the decimal point.
Instead, the position of the decimal point relative to the beginning of
BUF is stored in an integer variable whose address is passed in DECPT.
Thus, if BUF is returned as "1234" and *DECPT as 1, this corresponds to
a value of 1.234; if *DECPT is -1, this corresponds to a value of
0.01234, etc.

The sign is also not included in BUF's value.  If VALUE is negative,
`ecvtbuf' puts a nonzero value into the variable whose address is
passed in SIGN; otherwise it stores zero in *SIGN.

The least-significant digit in BUF is rounded.

`ecvtbuf' produces the string "NaN" if VALUE is a NaN, and "Inf" or
"Infinity" if VALUE is an infinity (the longer form is produced when
NDIGITS is 8 or more).

Return Value
------------

A pointer to BUF.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: fdopen,  Next: feof,  Prev: fcvtbuf,  Up: Alphabetical List

fdopen
======

Syntax
------

     #include <stdio.h>

     FILE *fdopen(int fd, const char *mode);

Description
-----------

This function opens a stream-type file that uses the given FD file,
which must already be open.  The file is opened with the modes
specified by MODE, which is the same as for `fopen'.  *Note fopen::.

Return Value
------------

The newly created `FILE *', or `NULL' on error.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     FILE *stdprn = fdopen(4, "w");


File: libc.info,  Node: feof,  Next: ferror,  Prev: fdopen,  Up: Alphabetical List

feof
====

Syntax
------

     #include <stdio.h>

     int feof(FILE *file);

Description
-----------

This function can be used to indicate if the given FILE is at the
end-of-file or not.

Return Value
------------

Nonzero at end-of-file, zero otherwise.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     while (!feof(stdin))
       gets(line);


File: libc.info,  Node: ferror,  Next: fflush,  Prev: feof,  Up: Alphabetical List

ferror
======

Syntax
------

     #include <stdio.h>

     int ferror(FILE *file);

Description
-----------

This function can be used to indicate if the given FILE has encountered
an error or not.  *Note clearerr::.

Return Value
------------

Nonzero for an error, zero otherwise.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     if (ferror(stdin))
       exit(1);


File: libc.info,  Node: fflush,  Next: ffs,  Prev: ferror,  Up: Alphabetical List

fflush
======

Syntax
------

     #include <stdio.h>

     int fflush(FILE *file);

Description
-----------

If FILE is not a `NULL' pointer, this function causes any unwritten
buffered data to be written out to the given FILE.  This is useful in
cases where the output is line buffered and you want to write a partial
line.

If FILE is a `NULL' pointer, `fflush' writes any buffered output to all
files opened for output.

Note that `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 `fsync' (*note fsync::) or `sync' (*note sync::)
is typically required to actually deliver data to the file(s).

Return Value
------------

Zero on success, -1 on error.  When called with a `NULL' pointer, -1
will be returned if an error happened while flushing some of the
streams (but `fflush' will still try to flush all the rest before it
returns).

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     printf("Enter value : ");
     fflush(stdout);
     scanf(result);


File: libc.info,  Node: ffs,  Next: fgetc,  Prev: fflush,  Up: Alphabetical List

ffs
===

Syntax
------

     #include <string.h>

     int ffs(int _mask);

Description
-----------

This function find the first (least significant) bit set in the input
value.

Return Value
------------

Bit position (1..32) of the least significant set bit, or zero if the
input value is zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     ffs(0) = 0
     ffs(1) = 1
     ffs(5) = 1
     ffs(96) = 6


File: libc.info,  Node: fgetc,  Next: fgetgrent,  Prev: ffs,  Up: Alphabetical List

fgetc
=====

Syntax
------

     #include <stdio.h>

     int fgetc(FILE *file);

Description
-----------

Returns the next character in the given FILE as an unsigned char.

Return Value
------------

The given char (value 0..255) or `EOF' at end-of-file.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     int c;
     while((c=fgetc(stdin)) != EOF)
       fputc(c, stdout);


File: libc.info,  Node: fgetgrent,  Next: fgetpos,  Prev: fgetc,  Up: Alphabetical List

fgetgrent
=========

Syntax
------

     #include <grp.h>

     struct group *fgetgrent(FILE *file);

Description
-----------

This function, in MS-DOS, is exactly the same as `getgrent' (*note
getgrent::).

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: fgetpos,  Next: fgets,  Prev: fgetgrent,  Up: Alphabetical List

fgetpos
=======

Syntax
------

     #include <stdio.h>

     int fgetpos(FILE *file, fpos_t *offset);

Description
-----------

This function records the current file pointer for FILE, for later use
by `fsetpos'.

*Note fsetpos::.  *Note ftell::.

Return Value
------------

Zero if successful, nonzero if not.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: fgets,  Next: File System Extensions,  Prev: fgetpos,  Up: Alphabetical List

fgets
=====

Syntax
------

     #include <stdio.h>

     char *fgets(char *buffer, int maxlength, FILE *file);

Description
-----------

This function reads as much of a line from a file as possible, stopping
when the buffer is full (MAXLENGTH-1 characters), an end-of-line is
detected, or `EOF' or an error is detected.  It then stores a `NULL' to
terminate the string.

Return Value
------------

The address of the buffer is returned on success, if `EOF' is
encountered before any characters are stored, or if an error is
detected, `NULL' is returned instead.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     char buf[100];
     while (fgets(buf, 100, stdin))
       fputs(buf, stdout);


File: libc.info,  Node: File System Extensions,  Next: __file_exists,  Prev: fgets,  Up: Alphabetical List

File System Extensions
======================

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 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:

       int function(__FSEXT_Fnumber func_number, int *rv, va_list args);

The FUNC_NUMBER identifies which function is to be emulated.  The file
`<sys/fsext.h>' defines the function numbers as follows:

`__FSEXT_nop'
     A no-op.  This is currently unused by the library functions.

`__FSEXT_open'
     An open handler (*note _open::).  This is called just before the
     library is about to issue the DOS OpenFile call on behalf of your
     program.

     If `_open' was called from the library function `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
     `O_NOLINK' was passed to `open' (*note open::).

     Do not use this extension to emulate symlinks.  Use
     `__FSEXT_readlink' handler instead.

`__FSEXT_creat'
     A create handler (*note _creat::, and *note _creatnew::).  Called
     when a file needs to be created.  Note that the handler should
     both create the "file" and open it.

     If `_creat' or `_creatnew' were called from the library functions
     `open' or `creat', then the file name passed to the handler will
     have all its symlink components resolved.

`__FSEXT_read'
     A read handler (*note _read::).  Called when data should be read
     from a "file".

`__FSEXT_write'
     A write handler (*note write::, and *note _write::).  Called to
     write data to a "file".  On "text" files it receives the
     _original_ (unconverted) buffer.

`__FSEXT_ready'
     A ready handler.  It is called by `select' library function (*note
     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 `<sys/fsext.h>'):

    `__FSEXT_ready_read'
          The "file" is ready for reading.

    `__FSEXT_ready_write'
          The "file" is ready for writing.

    `__FSEXT_ready_error'
          The "file" has an error condition set.


`__FSEXT_close'
     A close handler (*note _close::).  Called when the "file" should
     be closed.

`__FSEXT_fcntl'
     A file fcntl handler (*note fcntl::).

`__FSEXT_ioctl'
     A file ioctl handler (*note ioctl (General description)::).

`__FSEXT_lseek'
     A file lseek handler (*note lseek::).  Here for backwards
     compatibility.  Use `__FSEXT_llseek' instead.  If you have a
     `__FSEXT_llseek' handler you don't need a `__FSEXT_lseek' handler
     as `lseek' calls `llseek' internally.

`__FSEXT_llseek'
     A file llseek handler (*note llseek::).

`__FSEXT_link'
     A file link handler (*note 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.

`__FSEXT_unlink'
     A file unlink handler (*note remove::, and *note 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.

`__FSEXT_dup'
     A file dup handler (*note dup::).  This is called when a new
     descriptor is needed to refer to an existing descriptor.

`__FSEXT_dup2'
     A file dup2 handler (*note dup2::).  This is called when two
     different file descriptors are used to refer to the same open file.

`__FSEXT_stat'
     A file lstat handler (*note lstat::).  This extension should
     provide information about stated file.  If you provide this hook,
     function `stat' will be hooked too, as `stat' always calls `lstat'.

     If the handler is called as a result of a `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 `lstat' call and not a `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.

`__FSEXT_fstat'
     A file fstat handler (*note fstat::).  The extension should fill in
     various status information about the emulated file.

`__FSEXT_readlink'
     A file readlink handler (*note 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.

`__FSEXT_symlink'
     A file symlink handler (*note 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.

`__FSEXT_chmod'
     A file chmod handler (*note 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.

`__FSEXT_chown'
     A file chown handler (*note 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.

`__FSEXT_fchmod'
     A file fchmod handler (*note fchmod::).  This is called when the
     permissions are to be changed for an open file.

`__FSEXT_fchown'
     A file fchown handler (*note fchown::).  This is called when the
     ownership is to be changed for an open file.


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 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:

   *  Some function to create a connection to the extension.  This may
     be a custom function (such as `socket' for networking) or an
     extension to open (such as `/dev/ttyS0' to access the serial port).

   *  Initialization code that adds the open handler, if any.

   *  Overrides for the basic I/O functions, such as `read' and
     `write'.  This is a single function in the extension that uses the
     function number parameter to select an extension function.

   *  The core functionality of the extension, if any.


Please note that the special Unix filenames `/dev/null' and `/dev/tty'
are already mapped to the appropriate DOS names `NUL' and `CON',
respectively, so you don't need to write extensions for these.

Please note that the special Unix filenames `/dev/zero' and `/dev/full'
can be made available by calling the functions `__install_dev_zero'
(*note __install_dev_zero::) and `__install_dev_full' (*note
__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 `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 `__FSEXT_open' and `__FSEXT_creat' calls will be
passed to other File System Extensions by `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.


File: libc.info,  Node: __file_exists,  Next: __file_tree_walk,  Prev: File System Extensions,  Up: Alphabetical List

__file_exists
=============

Syntax
------

     #include <unistd.h>

     int __file_exists(const char *_fn);

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.

Return Value
------------

Zero if the file does not exist, nonzero if it does.  Note that this is
the opposite of what access() returns.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------


     if (__file_exists(fname))
       process_file(fname);


File: libc.info,  Node: __file_tree_walk,  Next: filelength,  Prev: __file_exists,  Up: Alphabetical List

__file_tree_walk
================

Syntax
------

     #include <dir.h>

     int __file_tree_walk(const char *dir,
                          int (*func)(const char *path,
                                      const struct ffblk *ff));

Description
-----------

This function recursively descends the directory hierarchy which starts
with DIR.  For each file in the hierarchy, `__file_tree_walk' calls the
user-defined function FUNC which is passed a pointer to a
`NULL'-terminated character array in PATH holding the full pathname of
the file, a pointer to a `ffblk' structure (*note findfirst::) FF with
a DOS filesystem information about that file.

This function always visits a directory before any of its siblings.  The
argument DIR must be a directory, or `__file_tree_walk' will fail and
set `errno' to `ENOTDIR'.  The directory DIR itself is never passed to
FUNC.

The tree traversal continues until one of the following events:

(1)  The tree is exhausted (i.e., all descendants of DIR are
processed).  In this case, `__file_tree_walk' returns 0, meaning a
success.

(2)  An invocation of FUNC returns a non-zero value.  In this case,
`__file_tree_walk' stops the tree traversal and returns whatever FUNC
returned.

(3)  An error is detected within `__file_tree_walk'.  In that case,
`ftw' returns -1 and sets `errno' (*note errno::) to a suitable value.

Return Value
------------

Zero in case the entire tree was successfully traversed, -1 if
`__file_tree_walk' detected some error during its operation, or any
other non-zero value which was returned by the user-defined function
FUNC.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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;
     }


File: libc.info,  Node: filelength,  Next: fileno,  Prev: __file_tree_walk,  Up: Alphabetical List

filelength
==========

Syntax
------

     #include <io.h>

     long filelength(int fhandle);

Description
-----------

This function returns the size, in bytes, of a file whose handle is
specified in the argument FHANDLE.  To get the handle of a file opened
by `fopen' (*note fopen::) or `freopen' (*note freopen::), you can use
`fileno' macro (*note fileno::).

Return Value
------------

The size of the file in bytes, or (if any error occurred) -1L and
`errno' set to a value describing the cause of the failure.  If the
file's length is larger than a 32-bit `unsigned int' can hold, `errno'
will be set to `EOVERFLOW'.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

       printf("Size of file to which STDIN is redirected is %ld\n",
               filelength(0));


File: libc.info,  Node: fileno,  Next: findfirst,  Prev: filelength,  Up: Alphabetical List

fileno
======

Syntax
------

     #include <stdio.h>

     int fileno(FILE *file);

Description
-----------

This function returns the raw file descriptor number that FILE uses for
I/O.

Return Value
------------

The file descriptor number.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: findfirst,  Next: findnext,  Prev: fileno,  Up: Alphabetical List

findfirst
=========

Syntax
------

     #include <dir.h>

     int findfirst(const char *pathname, struct ffblk *ffblk, int attrib);

Description
-----------

This function and the related `findnext' (*note findnext::) are used to
scan directories for the list of files therein.  The PATHNAME is a
wildcard that specifies the directory and files to search for (such as
`subdir/*.c'), FFBLK is a structure to hold the results and state of
the search, and ATTRIB is a combination of the following:

`FA_RDONLY'
     Include read-only files in the search (Ignored.)

`FA_HIDDEN'
     Include hidden files in the search

`FA_SYSTEM'
     Include system files in the search

`FA_LABEL'
     Include the volume label in the search

`FA_DIREC'
     Include subdirectories in the search

`FA_ARCH'
     Include modified files in the search (Ignored.)


If a file has flag bits that are not specified in the ATTRIB parameter,
the file will be excluded from the results.  Thus, if you specified
`FA_DIREC' and `FA_LABEL', subdirectories and the volume label will be
included in the results.  Hidden and system files will be excluded.

Since `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 FFBLK, which is extended when
the LFN API (*note LFN: _use_lfn.) is supported.  Fields marked LFN are
only valid if the `lfn_magic' member is set to "LFN32".

     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 */
     }

Return Value
------------

Zero if a match is found, nonzero if none found.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);
     }


File: libc.info,  Node: findnext,  Next: _fixpath,  Prev: findfirst,  Up: Alphabetical List

findnext
========

Syntax
------

     #include <dir.h>

     int findnext(struct ffblk *ffblk);

Description
-----------

This finds the next file in the search started by `findfirst'.  *Note
findfirst::.

Return Value
------------

Zero if there was a match, else nonzero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _fixpath,  Next: flock,  Prev: findnext,  Up: Alphabetical List

_fixpath
========

Syntax
------

     #include <sys/stat.h>

     void _fixpath(const char *in_path, char *out_path);

Description
-----------

This function canonicalizes the input path IN_PATH and stores the
result in the buffer pointed to by 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 OUT_PATH, but long filenames are left intact.  *Note
_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
OUT_PATH.  Using ANSI-standard constant `FILENAME_MAX' (defined on
`stdio.h') or Posix-standard constant `PATH_MAX' (defined on
`limits.h') is recommended.

Return Value
------------

None.  If the length of the returned path name exceeds `FILENAME_MAX',
`errno' is set to `ENAMETOOLONG'.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     char oldpath[100], newpath[FILENAME_MAX];
     scanf("%s", oldpath);
     _fixpath(oldpath, newpath);
     printf("that really is %s\n", newpath);


File: libc.info,  Node: flock,  Next: floor,  Prev: _fixpath,  Up: Alphabetical List

flock
=====

Syntax
------

     #include <sys/file.h>

     int flock (int _fildes, int _op);

Description
-----------

Apply or remove an advisory lock on an open file.  The file is specified
by file handle _FILDES.  Valid operations are given below:

`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 `LOCK_SH' requests are treated as if they
     were `LOCK_EX' requests.

`LOCK_EX'
     Exclusive lock.  Only one process may hold an exclusive lock for a
     given file at a given time.

`LOCK_UN'
     Unlock the file.

`LOCK_NB'
     Don't block when locking.  May be specified (by or'ing) along with
     one of the other operations.

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, `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 `F_SETLK' (non-blocking) or `F_SETLKW'
(blocking) commands to `fcntl', *note 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 `flock' by `or'ing `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 `LOCK_NB' will cause
the implementation to use `F_SETLK' instead of `F_SETLKW', which will
return an error if the lock cannot be obtained.

Return Value
------------

On success, zero is returned.  On error, -1 is returned, and `errno' is
set appropriately.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)

Notes:

  1. 4.4BSD (the flock (2) call first appeared in 4.2BSD).

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);


File: libc.info,  Node: floor,  Next: _flush_disk_cache,  Prev: flock,  Up: Alphabetical List

floor
=====

Syntax
------

     #include <math.h>

     double floor(double x);

Description
-----------

This function computes the largest integer not greater than X.

Return Value
------------

The largest integer value less than or equal to X.  Infinities and
`NaN's are returned unchanged.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: _flush_disk_cache,  Next: fmod,  Prev: floor,  Up: Alphabetical List

_flush_disk_cache
=================

Syntax
------

     #include <io.h>

     void _flush_disk_cache (void);

Description
-----------

Attempts to update the disk with the data cached in the write-behind
disk caches (such as `SmartDrv' and the built-in Windows 95 disk cache).

Note that this does *not* flush the DOS buffers.  You need to call
`fsync' (*note fsync::) or `close' (*note close::) to force DOS to
commit the file data to the disk; `sync' (*note sync::) does that for
all open files, and also calls `_flush_disk_cache'.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

       /* Make sure all cached data for a handle FD is actually
          written to disk.  */
       fsync (fd);
       _flush_disk_cache ();


File: libc.info,  Node: fmod,  Next: _fmode,  Prev: _flush_disk_cache,  Up: Alphabetical List

fmod
====

Syntax
------

     #include <math.h>

     double fmod(double x, double y);

Description
-----------

This function computes the remainder of `X/Y', which is X - iY for some
integer i such that iY < X < (i+1)Y.

Return Value
------------

The remainder of X/Y.  If X is `Inf' or `NaN', the return value is
`NaN' and `errno' is set to `EDOM'.  If Y is zero, the return value is
zero (but `errno' is not changed).

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: _fmode,  Next: fnmatch,  Prev: fmod,  Up: Alphabetical List

_fmode
======

Syntax
------

     #include <fcntl.h>

     extern int _fmode;

Description
-----------

This variable may be set to `O_TEXT' or `O_BINARY' to specify the mode
that newly opened files should be opened in if the open call did not
specify.  *Note open::. *Note fopen::.

The default value is `O_TEXT'.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     _fmode = O_BINARY;


File: libc.info,  Node: fnmatch,  Next: fnmerge,  Prev: _fmode,  Up: Alphabetical List

fnmatch
=======

Syntax
------

     #include <fnmatch.h>

     int fnmatch(const char *pattern, const char *string, int flags);

Description
-----------

This function indicates if STRING matches the PATTERN.  The PATTERN may
include the following special characters:

`*'
     Matches zero of more characters.

`?'
     Matches exactly one character.

`[...]'
     Matches one character if it's in a range of characters.  If the
     first character is `!', 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 `-' to indicate all characters in that range.  For example,
     `[a-d]' matches `a', `b', `c', or `d'.  If you want to include the
     literal `-' in the range, make it the first character, like in
     `[-afz]'.

`\'
     Causes the next character to not be treated as a wildcard.  For
     example, `\*' matches an asterisk.  This feature is not available
     if FLAGS includes `FNM_NOESCAPE', in which case `\' is treated as
     a directory separator.


The value of FLAGS is a combination of zero of more of the following:

`FNM_PATHNAME'
     This means that the STRING should be treated as a pathname, in
     that the slash characters `/' and `\' in STRING never match any of
     the wildcards in PATTERN.

`FNM_NOESCAPE'
     If this flag is *not* set, the backslash `\' may be used in
     PATTERN for quoting special characters.  If this flag *is* set,
     `\' is treated as a directory separator.

`FNM_NOCASE'
     If this flag is set, `fnmatch' matches characters
     case-insensitively, including in character ranges like `[a-f]'.
     Note that the case-folding is done by calling `toupper' (*note
     toupper::), and thus might be sensitive to the current locale.

`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 `FNM_PATHNAME' is
     set, a dot after a slash also doesn't match any wildcards.


The DJGPP implementation treats forward slashes and backslashes as equal
when `FNM_NOESCAPE' is set, since on DOS/Windows these two characters
are both used as directory separators in file names.

Return Value
------------

Zero if the string matches, `FNM_NOMATCH' if it does not.  Posix
defines an additional `FNM_ERROR' code that's returned in case of an
error, but the current implementation never returns it.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)

Notes:

  1. The equal handling of `\' and `/' is DJGPP-specific.

Example
-------

     if (fnmatch("*.[ch]", filename, FNM_PATHNAME|FNM_NOCASE))
       do_source_file(filename);


File: libc.info,  Node: fnmerge,  Next: fnsplit,  Prev: fnmatch,  Up: Alphabetical List

fnmerge
=======

Syntax
------

     #include <dir.h>

     void fnmerge (char *path, const char *drive, const char *dir,
     		const char *name, const char *ext);

Description
-----------

This function constructs a file PATH from its components DRIVE, DIR,
NAME, and EXT.  If any of these is a `NULL' pointer, it won't be used.
Usually, the DRIVE string should include the trailing colon ``:'', the
DIR string should include the trailing slash ``/'' or backslash ``\'',
and the EXT string should include the leading dot ``.''.  However, if
any of these isn't present, `fnmerge' will add them.

*Note fnsplit::.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     char buf[MAXPATH];
     fnmerge(buf, "d:", "/foo/", "data", ".txt");


File: libc.info,  Node: fnsplit,  Next: fopen,  Prev: fnmerge,  Up: Alphabetical List

fnsplit
=======

Syntax
------

     #include <dir.h>

     int fnsplit (const char *path, char *drive, char *dir,
     		char *name, char *ext);

Description
-----------

This function decomposes a PATH into its components.  It is smart
enough to know that `.' and `..' are directories, and that file names
with a leading dot, like `.emacs', are not all extensions.

The DRIVE, DIR, NAME and EXT arguments should all be passed, but some
or even all of them might be `NULL' pointers.  Those of them which are
non-`NULL' should point to buffers which have enough room for the
strings they would hold.  The constants `MAXDRIVE', `MAXDIR', `MAXFILE'
and `MAXEXT', defined on dir.h, define the maximum length of these
buffers.

*Note fnmerge::.

Return Value
------------

A flag that indicates which components were found:

`DRIVE'
     The drive letter was found.

`DIRECTORY'
     A directory or subdirectories was found.

`FILENAME'
     A filename was found.

`EXTENSION'
     An extension was found.

`WILDCARDS'
     The path included `*' or `?'.


Portability
-----------

ANSI/ISO C   No
POSIX        No

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"


File: libc.info,  Node: fopen,  Next: fork,  Prev: fnsplit,  Up: Alphabetical List

fopen
=====

Syntax
------

     #include <stdio.h>

     FILE *fopen(const char *filename, const char *mode);

Description
-----------

This function opens a stream corresponding to the named FILENAME with
the given MODE.  The mode can be one of the following:

`r'
     Open an existing file for reading.

`w'
     Create a new file (or truncate an existing file) and open it for
     writing.

`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.


Followed by any of these characters:

`b'
     Force the file to be open in binary mode instead of the default
     mode.

     When called to open the console in binary mode, `fopen' will
     disable the generation of `SIGINT' when you press `Ctrl-C'
     (`Ctrl-Break' will still cause `SIGINT'), because many programs
     that use binary reads from the console will also want to get the
     `^C' characters.  You can use the `__djgpp_set_ctrl_c' library
     function (*note __djgpp_set_ctrl_c::) if you want `Ctrl-C' to
     generate interrupts while console is read in binary mode.

`t'
     Force the file to be open in text mode instead of the default mode.

`+'
     Open the file as with `O_RDWR' so that both reads and writes can
     be done to the same file.


If the file is open for both reading and writing, you must call
`fflush', `fseek', or `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 `b' or `t' is not specified in MODE, the file type is chosen by the
value of `fmode' (*note _fmode::).

You can open directories using `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
`__djgpp_share_flags'.  *Note __djgpp_share_flags::.

Return Value
------------

A pointer to the `FILE' object, or `NULL' if there was an error.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     FILE *f = fopen("foo", "rb+"); /* open existing file for read/write,
                                     * binary mode */


File: libc.info,  Node: fork,  Next: fpathconf,  Prev: fopen,  Up: Alphabetical List

fork
====

Syntax
------

     #include <unistd.h>

     pid_t fork(void);

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.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: fpathconf,  Next: fpclassify,  Prev: fork,  Up: Alphabetical List

fpathconf
=========

Syntax
------

     #include <unistd.h>

     long fpathconf(int fd, int name);

Description
-----------

Returns configuration information on the filesystem that the open file
resides on.  *Note pathconf::.  If the filesystem cannot be determined
from the file handle FD (e.g., for character devices), `fpathconf' will
return the info for the current drive.

Return Value
------------

The configuration value; for details, see *Note pathconf::.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: fpclassify,  Next: __fpclassifyd,  Prev: fpathconf,  Up: Alphabetical List

fpclassify
==========

Syntax
------

     #include <math.h>

Description
-----------

The macro `fpclassify' returns the kind of the floating point value
supplied.

Return Value
------------

`FP_INFINITE', `FP_NAN', `FP_NORMAL', `FP_SUBNORMAL', `FP_ZERO' or
`FP_UNNORMAL'.

Portability
-----------

ANSI/ISO C   C99; not C89

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");
     }


File: libc.info,  Node: __fpclassifyd,  Next: __fpclassifyf,  Prev: fpclassify,  Up: Alphabetical List

__fpclassifyd
=============

Syntax
------

     #include <math.h>

     int __fpclassifyd(double);

Description
-----------

Returns the kind of the floating point value supplied. You should use
the type generic macro `fpclassify' (*note fpclassify::) instead of
this function.

Return Value
------------

`FP_INFINITE', `FP_NAN', `FP_NORMAL', `FP_SUBNORMAL' or `FP_ZERO'.

Portability
-----------

ANSI/ISO C   C99; not C89

Example
-------

     if( __fpclassifyd(0.0) != FP_ZERO )
     {
       printf("Something is wrong with the implementation!\n");
     }


File: libc.info,  Node: __fpclassifyf,  Next: __fpclassifyld,  Prev: __fpclassifyd,  Up: Alphabetical List

__fpclassifyf
=============

Syntax
------

     #include <math.h>

     int __fpclassifyf(float);

Description
-----------

Returns the kind of the floating point value supplied. You should use
the type generic macro `fpclassify' (*note fpclassify::) instead of
this function.

Return Value
------------

`FP_INFINITE', `FP_NAN', `FP_NORMAL', `FP_SUBNORMAL' or `FP_ZERO'.

Portability
-----------

ANSI/ISO C   C99; not C89

Example
-------

     if( __fpclassifyf(0.0F) != FP_ZERO )
     {
       printf("Something is wrong with the implementation!\n");
     }


File: libc.info,  Node: __fpclassifyld,  Next: _fpreset,  Prev: __fpclassifyf,  Up: Alphabetical List

__fpclassifyld
==============

Syntax
------

     #include <math.h>

     int __fpclassifyld(long double);

Description
-----------

Returns the kind of the floating point value supplied. You should use
the type generic macro `fpclassify' (*note fpclassify::) instead of
this function.

Return Value
------------

`FP_INFINITE', `FP_NAN', `FP_NORMAL', `FP_SUBNORMAL', `FP_ZERO' or
`FP_UNNORMAL'.

Portability
-----------

ANSI/ISO C   C99; not C89

Example
-------

     if( __fpclassifyld(0.0L) != FP_ZERO )
     {
       printf("Something is wrong with the implementation!\n");
     }


File: libc.info,  Node: _fpreset,  Next: fprintf,  Prev: __fpclassifyld,  Up: Alphabetical List

_fpreset
========

Syntax
------

     #include <float.h>

     void _fpreset(void);

Description
-----------

Resets the FPU completely.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: fprintf,  Next: fpurge,  Prev: _fpreset,  Up: Alphabetical List

fprintf
=======

Syntax
------

     #include <stdio.h>

     int fprintf(FILE *file, const char *format, ...);

Description
-----------

Prints formatted output to the named file.  *Note printf::.

Return Value
------------

The number of characters written.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: fpurge,  Next: fputc,  Prev: fprintf,  Up: Alphabetical List

fpurge
======

Syntax
------

     #include <stdio.h>

     int fpurge(FILE *file);

Description
-----------

If 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 `stdin').

Return Value
------------

Zero on success, -1 on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: fputc,  Next: fputs,  Prev: fpurge,  Up: Alphabetical List

fputc
=====

Syntax
------

     #include <stdio.h>

     int fputc(int character, FILE *file);

Description
-----------

This function writes the given CHARACTER to the given `file'.

Return Value
------------

The given character [0..255] or `EOF'.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     fputc('\n', stdout);


File: libc.info,  Node: fputs,  Next: fread,  Prev: fputc,  Up: Alphabetical List

fputs
=====

Syntax
------

     #include <stdio.h>

     int fputs(const char *string, FILE *file);

Description
-----------

This function copies all the characters of STRING (except the trailing
`NULL') to the given FILE.

Return Value
------------

A nonnegative number on success, `EOF' on error.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     fputs("Hello\n", stdout);


File: libc.info,  Node: fread,  Next: free,  Prev: fputs,  Up: Alphabetical List

fread
=====

Syntax
------

     #include <stdio.h>

     size_t fread(void *buffer, size_t size, size_t number, FILE *file);

Description
-----------

This function reads SIZE*NUMBER characters from FILE to BUFFER.

Return Value
------------

The number of items of size SIZE read, or less if there was an error.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     int foo[10];
     fread(foo, sizeof(int), 10, stdin);


File: libc.info,  Node: free,  Next: freopen,  Prev: fread,  Up: Alphabetical List

free
====

Syntax
------

     #include <stdlib.h>

     void free(void *ptr);

Description
-----------

Returns the allocated memory to the heap (*note malloc::).  If the PTR
is `NULL', `free' does nothing.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     char *q = malloc(20);
     free(q);


File: libc.info,  Node: freopen,  Next: frexp,  Prev: free,  Up: Alphabetical List

freopen
=======

Syntax
------

     #include <stdio.h>

     FILE *freopen(const char *filename, const char *mode, FILE *file);

Description
-----------

This function closes FILE if it was open, then opens a new file like
`fopen(filename, mode)' (*note fopen::) but it reuses FILE.

This is useful to, for example, associate `stdout' with a new file.

Return Value
------------

The new file, or `NULL' on error.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     freopen("/tmp/stdout.dat", "wb", stdout);


File: libc.info,  Node: frexp,  Next: fscanf,  Prev: freopen,  Up: Alphabetical List

frexp
=====

Syntax
------

     #include <math.h>

     double frexp(double x, int *pexp);

Description
-----------

This function separates the given value X into a mantissa m in the
range `[0.5,1)' and an exponent e, such that m*2^e = X.  It returns the
value of the mantissa and stores the integer exponent in *PEXP.

Return Value
------------

The mantissa.  If the value of X is `NaN' or `Inf', the return value is
`NaN', zero is stored in `*pexp', and `errno' is set to `EDOM'.  If X
is zero, *PEXP and the return value are also both zero.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: fscanf,  Next: fseek,  Prev: frexp,  Up: Alphabetical List

fscanf
======

Syntax
------

     #include <stdio.h>

     int fscanf(FILE *file, const char *format, ...);

Description
-----------

This function scans formatted text from FILE and stores it in the
variables pointed to by the arguments.  *Note scanf::.

Return Value
------------

The number of items successfully scanned.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: fseek,  Next: fseeko,  Prev: fscanf,  Up: Alphabetical List

fseek
=====

Syntax
------

     #include <stdio.h>

     int fseek(FILE *file, long offset, int mode);

Description
-----------

This function moves the file pointer for FILE according to MODE:

`SEEK_SET'
     The file pointer is moved to the offset specified.

`SEEK_CUR'
     The file pointer is moved relative to its current position.

`SEEK_END'
     The file pointer is moved to a position OFFSET bytes from the end
     of the file.  The offset is usually nonpositive in this case.


_Warning!_ The ANSI standard only allows values of zero for OFFSET when
MODE is not `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 `fseek' operations may not do exactly what you
expect.

Also, since `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 `fseek'.  Portable programs should call `ftell' after
`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, `lseek' will not return with an error in such cases
either.

Return Value
------------

Zero if successful, nonzero if not.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     fseek(stdin, 12, SEEK_CUR); /* skip 12 bytes */


File: libc.info,  Node: fseeko,  Next: fsetpos,  Prev: fseek,  Up: Alphabetical List

fseeko
======

Syntax
------

     #include <stdio.h>

     int fseeko(FILE *file, off_t offset, int mode);

Description
-----------

`fseeko' is a wrapper function of `fseek' (*note fseek::).  So it is
identical to `fseek', except that the offset argument of `fseeko' is of
type `off_t' instead of `long'.

This function moves the file pointer for FILE according to MODE:

`SEEK_SET'
     The file pointer is moved to the offset specified.

`SEEK_CUR'
     The file pointer is moved relative to its current position.

`SEEK_END'
     The file pointer is moved to a position OFFSET bytes from the end
     of the file.  The offset is usually nonpositive in this case.


_Warning!_ The ANSI standard only allows values of zero for OFFSET when
MODE is not `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 `fseeko' operations may not do exactly what you
expect.

Also, since `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 `fseeko'.  Portable programs should call `ftello' after
`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, `lseek' will not return with an error in such cases
either.

Return Value
------------

Zero if successful, nonzero if not.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     fseeko(stdin, 12, SEEK_CUR); /* skip 12 bytes */


File: libc.info,  Node: fsetpos,  Next: __FSEXT_add_open_handler,  Prev: fseeko,  Up: Alphabetical List

fsetpos
=======

Syntax
------

     #include <stdio.h>

     int fsetpos(FILE *file, const fpos_t *offset);

Description
-----------

This function moves the file pointer for FILE to position OFFSET, as
recorded by `fgetpos'.

*Note fgetpos::.  *Note fseek::.

Return Value
------------

Zero if successful, nonzero if not.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: __FSEXT_add_open_handler,  Next: __FSEXT_alloc_fd,  Prev: fsetpos,  Up: Alphabetical List

__FSEXT_add_open_handler
========================

Syntax
------

     #include <sys/fsext.h>

     int __FSEXT_add_open_handler(__FSEXT_Function *_function);

Description
-----------

This function is part of the *Note File System Extensions::.  It is used
to add a handler for functions that do not get passed descriptors, such
as `_open' and `_creat'.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     static int
     _my_handler(__FSEXT_Fnumber n, int *rv, va_list args)
     {
       . . .
     }

     int main()
     {
       __FSEXT_add_open_handler(_my_handler);
     }


File: libc.info,  Node: __FSEXT_alloc_fd,  Next: __FSEXT_call_open_handlers,  Prev: __FSEXT_add_open_handler,  Up: Alphabetical List

__FSEXT_alloc_fd
================

Syntax
------

     #include <sys/fsext.h>

     int __FSEXT_alloc_fd(__FSEXT_Function *_function);

Description
-----------

This function is part of the *Note 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 `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 `dup' function; this makes all of the handles use a
single entry in the System File Table, and thus be independent of what
the `FILES=' parameter of `CONFIG.SYS' says.  `__FSEXT_alloc_fd' also
assigns the handler function for the handle it returns.

The module is responsible for calling `_close' on the descriptor after
setting the handler function to zero in the extended close handler.

Return Value
------------

If successful, a new file descriptor is returned. On error, a negative
number is returned and `errno' is set to indicate the error.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------


     int socket()
     {
       int fd = __FSEXT_alloc_fd(socket_handler);
       init_socket(fd);
       return fd;
     }


File: libc.info,  Node: __FSEXT_call_open_handlers,  Next: __FSEXT_get_data,  Prev: __FSEXT_alloc_fd,  Up: Alphabetical List

__FSEXT_call_open_handlers
==========================

Syntax
------

     #include <sys/fsext.h>

     int __FSEXT_call_open_handlers(__FSEXT_Fnumber _function_number,
     			       int *rv, va_list _args);

Description
-----------

This function is part of the *Note File System Extensions::.  It is used
internally to libc.a to allow extensions to get an opportunity to
override the `_open' and `_creat' functions.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __FSEXT_get_data,  Next: __FSEXT_get_function,  Prev: __FSEXT_call_open_handlers,  Up: Alphabetical List

__FSEXT_get_data
================

Syntax
------

     #include <sys/fsext.h>

     void *__FSEXT_get_data(int _fd);

Description
-----------

This function is part of the *Note File System Extensions::.  It is used
to retrieve a descriptor-specific pointer that was previously stored by
`__FSEXT_set_data' (*note __FSEXT_set_data::).  The pointer is not
otherwise used.

*Note __FSEXT_set_data::, for an example of how this may be used.

Return Value
------------

Returns the stored pointer, or NULL if there was an error (or no
pointer had been stored).

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __FSEXT_get_function,  Next: __FSEXT_set_data,  Prev: __FSEXT_get_data,  Up: Alphabetical List

__FSEXT_get_function
====================

Syntax
------

     #include <sys/fsext.h>

     __FSEXT_Function *__FSEXT_get_function(int _fd);

This function is part of the *Note File System Extensions::.  It is used
internal to libc.a to redirect I/O requests to the appropriate
extensions.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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() */
     }


File: libc.info,  Node: __FSEXT_set_data,  Next: __FSEXT_set_function,  Prev: __FSEXT_get_function,  Up: Alphabetical List

__FSEXT_set_data
================

Syntax
------

     #include <sys/fsext.h>

     void * __FSEXT_set_data(int _fd, void *_data);

Description
-----------

This function is part of the *Note File System Extensions::.  It is used
to store a descriptor-specific pointer that can later be retrieved by
`__FSEXT_get_data' (*note __FSEXT_get_data::).  The pointer is not
otherwise used.

This is useful when writing an extension that may be handling several
open pseudo-files.  `__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 `__FSEXT_get_data'.

Return Value
------------

Returns the pointer you passed it, or NULL if there was an error.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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;

            ...
         }
     }


File: libc.info,  Node: __FSEXT_set_function,  Next: fstat,  Prev: __FSEXT_set_data,  Up: Alphabetical List

__FSEXT_set_function
====================

Syntax
------

     #include <sys/fsext.h>

     int __FSEXT_set_function(int _fd, __FSEXT_Function *_function);

Description
-----------

This function is part of the *Note 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.

Return Value
------------

Zero in case of success, non-zero in case of failure (like if _FD is
negative).

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);
     }


File: libc.info,  Node: fstat,  Next: fstatvfs,  Prev: __FSEXT_set_function,  Up: Alphabetical List

fstat
=====

Syntax
------

     #include <sys/stat.h>

     int fstat(int file, struct stat *sbuf);

Description
-----------

This function obtains the status of the open file FILE and stores it in
SBUF.  *Note stat::, for the description of members of `struct stat'.

The `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 `st_size' as an unsigned value.

For some drives `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 `struct stat' are very expensive to compute.  If your
application is a heavy user of `fstat' and is too slow, you can disable
computation of the members your application doesn't need, as described
in *Note _djstat_flags::.

Return Value
------------

Zero on success, nonzero on failure (and `errno' set).

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

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");

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 `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 `fflush' and `fsync'.  Otherwise, the buffering of
the library I/O functions and the OS might cause stale info to be
returned.

Implementation Notes
--------------------

Supplying a 100% Unix-compatible `fstat' function under DOS is an
implementation nightmare.  The following notes describe some of the
obscure points specific to `fstat's behavior in DJGPP.

1. The `drive' for character devices (like `con', `/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 `st_inode'
field will be `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
`stat' and `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 `st_dev' member.)

3. On all versions of Windows except Windows 3.X, the inode number is
invented using the file name.  `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.: `foo.txt', `./foo.txt',
`../somedir/foo.txt').  If file names cannot be used, `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 `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 `_djstat_flags' (*note _djstat_flags::) controls what
hard-to-get fields of `struct stat' are needed by the application.


File: libc.info,  Node: fstatvfs,  Next: fsync,  Prev: fstat,  Up: Alphabetical List

fstatvfs
========

Syntax
------

     #include <sys/types.h>
     #include <sys/statvfs.h>

     int fstatvfs (int fd, struct statvfs *sbuf);

Description
-----------

This function returns information about the "filesystem" (FS)
containing the file referred to by the file descriptor FD and stores it
in SBUF, which has the structure below:

     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 */
     };

Note that if INT 21h is hooked by a TSR, the total size is limited to
approximately 2GB (*note statvfs::).

Return Value
------------

Zero on success, nonzero on failure (and `errno' set).

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: fsync,  Next: ftell,  Prev: fstatvfs,  Up: Alphabetical List

fsync
=====

Syntax
------

     #include <unistd.h>

     int fsync(int file);

Description
-----------

Forces all information about the file with the given descriptor to be
synchronized with the disk image.  Works by calling DOS function 0x68.
_Warning_: External disk caches are not flushed by this function.

`fsync' does not support directories.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     fsync(fileno(stdout));


File: libc.info,  Node: ftell,  Next: ftello,  Prev: fsync,  Up: Alphabetical List

ftell
=====

Syntax
------

     #include <stdio.h>

     long ftell(FILE *file);

Description
-----------

Returns the current file position for `file'.  This is suitable for a
future call to `fseek'.

Return Value
------------

The file position, or -1 on error.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     long p = ftell(stdout);


File: libc.info,  Node: ftello,  Next: ftime,  Prev: ftell,  Up: Alphabetical List

ftello
======

Syntax
------

     #include <stdio.h>

     off_t ftello(FILE *file);

Description
-----------

`ftello' is a wrapper function of `ftell' (*note ftell::).  So it is
identical to `ftell', except that the return value of `ftello' is of
type `off_t' instead of `long'.

Returns the current file position for `file'.  This is suitable for a
future call to `fseeko'.

Return Value
------------

The file position, or -1 on error.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     off_t p = ftello(stdout);


File: libc.info,  Node: ftime,  Next: ftruncate,  Prev: ftello,  Up: Alphabetical List

ftime
=====

Syntax
------

     #include <sys/timeb.h>

     int ftime(struct timeb *buf);

Description
-----------

This function stores the current time in the structure BUF.  The format
of `struct timeb' is:

     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 */
     };

Return Value
------------

Zero on success, nonzero on error.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     struct timeb t;
     ftime(&t);


File: libc.info,  Node: ftruncate,  Next: ftw,  Prev: ftime,  Up: Alphabetical List

ftruncate
=========

Syntax
------

     #include <unistd.h>

     int ftruncate(int handle, off_t where);

Description
-----------

This function truncates the file open on HANDLE at byte position WHERE.
The file pointer associated with HANDLE is not changed.

Note that this function knows nothing about buffering by stdio functions
like `fwrite' and `fprintf', so if HANDLE comes from a `FILE' object,
you need to call `fflush' before calling this function.

`ftruncate' does not support directories.

Return Value
------------

Zero for success, nonzero for failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     int x = open("data", O_WRONLY);
     ftruncate(x, 1000);
     close(x);


File: libc.info,  Node: ftw,  Next: _fwalk,  Prev: ftruncate,  Up: Alphabetical List

ftw
===

Syntax
------

     #include <ftw.h>

     int ftw(const char *dir,
             int (*func)(const char *path, struct stat *stbuf, int flag),
             int depth);

Description
-----------

This function recursively descends the directory hierarchy which starts
with DIR.  For each file in the hierarchy, `ftw' calls the user-defined
function FUNC which is passed a pointer to a `NULL'-terminated
character array in PATH holding the full pathname of the file, a
pointer to a `stat' structure (*note stat::) STBUF with a filesystem
information about that file, and an integer FLAG.  Possible values of
FLAG are:

`FTW_F'
     This is a regular file.

`FTW_D'
     This is a directory.

`FTW_VL'
     This is a volume label.

`FTW_DNR'
     This is a directory which cannot be read with `readdir()'.  (This
     will never happen in DJGPP.)

`FTW_NS'
     This file exists, but `stat' fails for it.


If FLAG is `FTW_DNR', the descendants of that directory won't be
processed.  If FLAG is `FTW_NS', then STBUF will be garbled.

This function always visits a directory before any of its siblings.  The
argument DIR must be a directory, or `ftw' will fail and set `errno' to
`ENOTDIR'.  The function FUNC is called with DIR as its argument before
the recursive descent begins.

The 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 DIR are
processed).  In this case, `ftw' returns 0, meaning a success.

(2)  An invocation of FUNC returns a non-zero value.  In this case,
`ftw' stops the tree traversal and returns whatever FUNC returned.

(3)  An error is detected within `ftw'.  In that case, `ftw' returns -1
and sets `errno' (*note errno::) to a suitable value.

Return Value
------------

Zero in case the entire tree was successfully traversed, -1 if `ftw'
detected some error during its operation, or any other non-zero value
which was returned by the user-defined function FUNC.

Implementation Notes
--------------------

This function uses `malloc' (*note malloc::) for dynamic memory
allocation during its operation.  If FUNC disrupts the normal flow of
code execution by e.g. calling `longjump' or if an interrupt handler
which never returns is executed, this memory will remain permanently
allocated.

This function calls `opendir()' and `readdir()' functions to read the
directory entries.  Therefore, you can control what files will your
FUNC get by setting the appropriate bits in the external variable
__OPENDIR_FLAGS.  *Note opendir::, for description of these bits.

This function also calls `stat' for every directory entry it passes to
FUNC.  If your application only needs some part of the information
returned in the `stat' structure, you can make your application
significantly faster by setting bits in the external variable
_DJSTAT_FLAGS (*note _djstat_flags:: for details).  The most expensive
`stat' features are `_STAT_EXEC_MAGIC' and `_STAT_DIRSIZE'.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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;
     }


File: libc.info,  Node: _fwalk,  Next: fwrite,  Prev: ftw,  Up: Alphabetical List

_fwalk
======

Syntax
------

     #include <libc/file.h>

     void _fwalk(void (*function)(FILE *file));

Description
-----------

For each open file in the system, the given FUNCTION is called, passing
the file pointer as its only argument.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     void pfile(FILE *x)
     { printf("FILE at %p\n", x); }

     _fwalk(pfile);


File: libc.info,  Node: fwrite,  Next: gcvt,  Prev: _fwalk,  Up: Alphabetical List

fwrite
======

Syntax
------

     #include <stdio.h>

     size_t fwrite(void *buffer, size_t size, size_t number, FILE *file);

Description
-----------

This function writes SIZE*NUMBER characters from BUFFER to FILE.

Return Value
------------

The number of items of size SIZE written, or less if there was an error.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     int foo[10];
     fwrite(foo, sizeof(int), 10, stdin);


File: libc.info,  Node: gcvt,  Next: _get_dev_info,  Prev: fwrite,  Up: Alphabetical List

gcvt
====

Syntax
------

     #include <stdlib.h>

     char * gcvt (double value, int ndigits, char *buf)

Description
-----------

This function converts its argument VALUE into a null-terminated string
of NDIGITS significant digits in BUF.  BUF should have enough space to
hold at least `NDIGITS + 7' characters.  The result roughly corresponds
to what is obtained by the following snippet:

      (void) sprintf(buf, "%.*g", ndigits, value);

except that trailing zeros and trailing decimal point are suppressed.

The least-significant digit in BUF is rounded.

`ecvtbuf' produces the string "NaN" if VALUE is a NaN, and "Inf" if
VALUE is an infinity.

Return Value
------------

A pointer to BUF.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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));


File: libc.info,  Node: _get_dev_info,  Next: _get_dos_version,  Prev: gcvt,  Up: Alphabetical List

_get_dev_info
=============

Syntax
------

     #include <io.h>

     short _get_dev_info(int handle);

Description
-----------

Given a file handle in HANDLE, this function returns the info word from
DOS IOCTL function 0 (Int 21h/AX=4400h).  HANDLE must refer to an open
file or device, otherwise the call will fail (and set `errno' to
`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 HANDLE.  The header `<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:

Bit(s)   Constant        Description
14       `_DEV_IOCTRL'   Device can process IOCTL functions 02h and 03h
13                       Device supports output-until-busy
11                       Device supports OPEN/CLOSE calls
8                        Unknown; set by MS-DOS 6.2x `KEYBXX.COM'
7        `_DEV_CDEV'     Always set for character devices
6                        End of file on input
5        `_DEV_RAW'      If set, device is in *raw* (binary) mode
5        `_DEV_RAW'      If clear, device is in *cooked* (text) mode
4                        Device uses Int 29h
3        `_DEV_CLOCK'    Clock device
2        `_DEV_NUL'      NUL device
1        `_DEV_STDOUT'   Standard output device
0        `_DEV_STDIN'    Standard input device

For a block device (a disk file):

Bit(s)   Constant        Description
15       `_DEV_REMOTE'   Device is remote (networked drive)
14                       Don't set file time stamp on close
11                       If set, non-removable media
11                       If clear, media is removable (e.g. floppy disk)
8                        Generate Int 24h if full disk or read past EOF
7        `_DEV_CDEV'     Always clear for disk files
6                        File has not been written to
5-0                      Drive number (0 = `A:')

Note that the functionality indicated by bit 8 for the block devices is
only supported by DOS version 4.

"Cooked" mode means that on input `C-<C>', `C-<P>', `C-<S>' and `C-<Z>'
are processed, on output `TAB's are expanded into spaces and `CR'
character is added before each `LF', and input is terminated when the
<RET> key is pressed.  In contrast, in "raw" mode, all the special
characters are passed verbatim, and the read operation waits until the
specified number of characters has been read.

Return Value
------------

The device information word described above.  In case of error, -1 is
returned and `errno' is set to `EBADF'.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

      int fd = open ("CLOCK$", O_RDONLY | O_BINARY);
      int clock_info = _get_dev_info (fd);


File: libc.info,  Node: _get_dos_version,  Next: __get_extended_key_string,  Prev: _get_dev_info,  Up: Alphabetical List

_get_dos_version
================

Syntax
------

     #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);

Description
-----------

This function gets the host OS version and flavor.  If the argument
TRUE_VERSION is non-zero, it will return a `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 `_osmajor' and `_osminor' will always be set to
the major and minor parts of the `advertised' version number.  The
external variable `_os_trueversion' will always be set to the true
version number.  `_osmajor', `_osminor' and `_os_trueversion' may
possibly be changed by `SETVER', even if 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 `SETVER' even if TRUE_VERSION is non-zero.

The external variable `_os_flavor' will point to a string which
describes the OEM name of the host OS variety.

Return Value
------------

`_get_dos_version()' returns the version number (true version number,
if 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.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: __get_extended_key_string,  Next: _get_fat_size,  Prev: _get_dos_version,  Up: Alphabetical List

__get_extended_key_string
=========================

Syntax
------

     #include <pc.h>

     const unsigned char * __get_extended_key_string(int xkey_code);

Description
-----------

Returns an ECMA-48 compliant representation of an extended key's scan
code in XKEY_CODE.

*Note getkey::.  *Note getxkey::.

Return Value
------------

A string based on the extended key's scan code XKEY_CODE:

Key           Normal      with Shift   with Ctrl   with Alt
`Up Arrow'    `ESC[A'                  `ESC[37~'   `ESC[59~'
`Down Arrow'  `ESC[B'                  `ESC[38~'   `ESC[60~'
`Left Arrow'  `ESC[C'                  `ESC[39~'   `ESC[61~'
`Right Arrow' `ESC[D'                  `ESC[40~'   `ESC[62~'
`Home'        `ESC[1~'                 `ESC[41~'   `ESC[63~'
`Insert'      `ESC[2~'                 `ESC[42~'   `ESC[64~'
`Delete'      `ESC[3~'                 `ESC[43~'   `ESC[65~'
`End'         `ESC[4~'                 `ESC[44~'   `ESC[66~'
`Page Up'     `ESC[5~'                 `ESC[45~'   `ESC[67~'
`Page Down'   `ESC[6~'                 `ESC[46~'   `ESC[68~'
`F1'          `ESC[[A'    `ESC[25~'    `ESC[47~'   `ESC[69~'
`F2'          `ESC[[B'    `ESC[26~'    `ESC[48~'   `ESC[70~'
`F3'          `ESC[[C'    `ESC[27~'    `ESC[49~'   `ESC[71~'
`F4'          `ESC[[D'    `ESC[28~'    `ESC[50~'   `ESC[72~'
`F5'          `ESC[[E'    `ESC[29~'    `ESC[51~'   `ESC[73~'
`F6'          `ESC[17~'   `ESC[30~'    `ESC[52~'   `ESC[74~'
`F7'          `ESC[18~'   `ESC[31~'    `ESC[53~'   `ESC[75~'
`F8'          `ESC[19~'   `ESC[32~'    `ESC[54~'   `ESC[76~'
`F9'          `ESC[20~'   `ESC[33~'    `ESC[55~'   `ESC[77~'
`F10'         `ESC[21~'   `ESC[34~'    `ESC[56~'   `ESC[78~'
`F11'         `ESC[23~'   `ESC[35~'    `ESC[57~'   `ESC[79~'
`F12'         `ESC[24~'   `ESC[36~'    `ESC[58~'   `ESC[80~'

Alt Key               Alt Key   
`Alt-A'   `ESC[81~'   `Alt-N'   `ESC[94~'
`Alt-B'   `ESC[82~'   `Alt-O'   `ESC[95~'
`Alt-C'   `ESC[83~'   `Alt-P'   `ESC[96~'
`Alt-D'   `ESC[84~'   `Alt-Q'   `ESC[97~'
`Alt-E'   `ESC[85~'   `Alt-R'   `ESC[98~'
`Alt-F'   `ESC[86~'   `Alt-S'   `ESC[99~'
`Alt-G'   `ESC[87~'   `Alt-T'   `ESC[100~'
`Alt-H'   `ESC[88~'   `Alt-U'   `ESC[101~'
`Alt-I'   `ESC[89~'   `Alt-V'   `ESC[102~'
`Alt-J'   `ESC[90~'   `Alt-W'   `ESC[103~'
`Alt-K'   `ESC[91~'   `Alt-X'   `ESC[104~'
`Alt-L'   `ESC[92~'   `Alt-Y'   `ESC[105~'
`Alt-M'   `ESC[93~'   `Alt-Z'   `ESC[106~'

`NULL' is returned if XKEY_CODE has no translation.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);
     }

     #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);
       }
     }


File: libc.info,  Node: _get_fat_size,  Next: __get_fd_flags,  Prev: __get_extended_key_string,  Up: Alphabetical List

_get_fat_size
=============

Syntax
------

     #include <dos.h>

     int _get_fat_size( const int drive );

Description
-----------

This function tries to determine the number of bits used to enumerate
the clusters by the FAT on drive number DRIVE. 1 == A:, 2 == B:, etc.,
0 == default drive.

This function will not succeed on DOS version < 4, setting `errno' to
`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 `_get_fs_type' (*note _get_fs_type::) can
be of use.

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.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);
     }


File: libc.info,  Node: __get_fd_flags,  Next: __get_fd_name,  Prev: _get_fat_size,  Up: Alphabetical List

__get_fd_flags
==============

Syntax
------

     #include <libc/fd_props.h>

     unsigned long __get_fd_flags(int fd);

Description
-----------

This internal functions gets the flags associated with file descriptor
FD, if any.  The flags are some properties that may be associated with
a file descriptor (*note __set_fd_properties::).

This function will return zero, if no flags are associated with FD.
The caller should first check that there are flags associated with FD
using `__has_fd_properties' (*note __has_fd_properties::), before
calling `__get_fd_flags'.  This will allow the cases of no flags and
the flags being zero to be distinguished.

Return Value
------------

The flags, if any; otherwise zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __get_fd_name,  Next: _get_fs_type,  Prev: __get_fd_flags,  Up: Alphabetical List

__get_fd_name
=============

Syntax
------

     #include <libc/fd_props.h>

     const char *__get_fd_name(int fd);

Description
-----------

This internal function gets the file name associated with the file
descriptor FD, if any.  The file name is one property that may be
associated with a file descriptor (*note __set_fd_properties::).

Return Value
------------

A pointer to the file name, if any; otherwise `NULL'.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _get_fs_type,  Next: _get_volume_info,  Prev: __get_fd_name,  Up: Alphabetical List

_get_fs_type
============

Syntax
------

     #include <dos.h>

     int _get_fs_type( const int drive,
                       char *const result_str );

Description
-----------

This function tries to extract the file system type of the drive number
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 RESULT_STR which must be at least 9
characters long.  If unsuccessful `errno' is set.

This function will not succeed on DOS version < 4, setting `errno' to
`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 `_get_fat_size' (*note _get_fat_size::) which will
reliably detect the right kind of FAT file system.

Return Value
------------

0 if the file system type was extracted successfully; otherwise -1.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);
     }


File: libc.info,  Node: _get_volume_info,  Next: getc,  Prev: _get_fs_type,  Up: Alphabetical List

_get_volume_info
================

Syntax
------

     #include <fcntl.h>

     unsigned _get_volume_info (const char *path,
                                int *max_file_len, int *max_path_len,
                                char *fsystype);

Description
-----------

This function returns filesystem information about the volume where
PATH resides.  Only the root directory name part is actually used; if
PATH does not specify the drive explicitly, or is a `NULL' pointer, the
current drive is used.  Upon return, the variable pointed to by
MAX_FILE_LEN contains the maximum length of a filename (including the
terminating zero), the variable pointed to by 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 FSYSTYPE, which should be long
enough (32 bytes are usually enough).  If any of these pointers is a
`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:

`_FILESYS_CASE_SENSITIVE'
     Specifies that file searches are case-sensitive.

`_FILESYS_CASE_PRESERVED'
     Filename letter-case is preserved in directory entries.

`_FILESYS_UNICODE'
     Filesystem uses Unicode characters in file and directory names.

`_FILESYS_LFN_SUPPORTED'
     Filesystem supports the "Long File Name" (LFN) API.

`_FILESYS_VOL_COMPRESSED'
     This volume is compressed.

`_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.

Return value
------------

A combination of the above bits if the LFN API is supported, or 0 (and
`errno' set to `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 `_FILESYS_UNKNOWN' and sets `errno' to either `ENODEV' or
`ENXIO'.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: getc,  Next: getcbrk,  Prev: _get_volume_info,  Up: Alphabetical List

getc
====

Syntax
------

     #include <stdio.h>

     int getc(FILE *file);

Description
-----------

Get one character from FILE.

Return Value
------------

The character ([0..255]) or `EOF' if eof or error.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     int c;
     while ((c=getc(stdin)) != EOF)
       putc(c, stdout);


File: libc.info,  Node: getcbrk,  Next: getch,  Prev: getc,  Up: Alphabetical List

getcbrk
=======

Syntax
------

     #include <dos.h>

     int getcbrk(void);

Description
-----------

Get the setting of the Ctrl-C checking flag in MS-DOS.

*Note setcbrk::.

Return Value
------------

0 if not checking, 1 if checking.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: getch,  Next: getchar,  Prev: getcbrk,  Up: Alphabetical List

getch
=====

Syntax
------

     #include <conio.h>

     int     getch(void);

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 `ungetch' (*note ungetch::), it is returned instead.  The
character is not echoed to the screen.  This function doesn't check for
special characters like `Ctrl-<C>'.

If the standard input handle is connected to the console, any pending
output in the `stdout' and `stderr' streams is flushed before reading
the input, if these streams are connected to the console.

Return Value
------------

The character.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: getchar,  Next: getche,  Prev: getch,  Up: Alphabetical List

getchar
=======

Syntax
------

     #include <stdio.h>

     int getchar(void);

Description
-----------

The same as `fgetc(stdin)' (*note fgetc::).

Return Value
------------

The character, or `EOF'.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: getche,  Next: getcwd,  Prev: getchar,  Up: Alphabetical List

getche
======

Syntax
------

     #include <conio.h>

     int getche(void);

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 `ungetch' (*note ungetch::), it is returned instead.  The
character is echoed to the screen.  This function doesn't check for
special characters like `Ctrl-<C>'.

If the standard input handle is connected to the console, any pending
output in the `stdout' and `stderr' streams is flushed before reading
the input, if these streams are connected to the console.

Return Value
------------

The character.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: getcwd,  Next: getdate,  Prev: getche,  Up: Alphabetical List

getcwd
======

Syntax
------

     #include <unistd.h>

     char *getcwd(char *buffer, int max);

Description
-----------

Get the current directory.  The return value includes the drive
specifier.

If BUFFER is `NULL', `getcwd' allocates a buffer of size MAX with
`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 MAX characters are required to specify the
current directory.

Return Value
------------

The buffer, either BUFFER or a newly-allocated buffer, or `NULL' on
error.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)

Notes:

  1. The behaviour when BUFFER is `NULL' is unspecified for POSIX.


Example
-------

     char *buf = (char *)malloc(PATH_MAX);
     if (buf && getcwd(buf, PATH_MAX))
     {
       printf("cwd is %s\n", buf);
       free(buf);
     }


File: libc.info,  Node: getdate,  Next: getdfree,  Prev: getcwd,  Up: Alphabetical List

getdate
=======

Syntax
------

     #include <dos.h>

     void getdate(struct date *);

Description
-----------

This function gets the current date.  The return structure is as
follows:

     struct date {
       short da_year;
       char  da_day;
       char  da_mon;
     };

*Note setdate::. *Note gettime::.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     struct date d;
     getdate(&d);


File: libc.info,  Node: getdfree,  Next: getdisk,  Prev: getdate,  Up: Alphabetical List

getdfree
========

Syntax
------

     #include <dos.h>

     void getdfree(unsigned char drive, struct dfree *ptr);

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:

     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 */
     };

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     struct dfree d;
     getdfree(3, &d); /* drive C: */


File: libc.info,  Node: getdisk,  Next: getdtablesize,  Prev: getdfree,  Up: Alphabetical List

getdisk
=======

Syntax
------

     #include <dir.h>

     int getdisk(void);

Description
-----------

Gets the current disk (0=A).

*Note setdisk::.

Return Value
------------

The current disk number.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     printf("This drive is %c:\n", getdisk() + 'A');


File: libc.info,  Node: getdtablesize,  Next: getegid,  Prev: getdisk,  Up: Alphabetical List

getdtablesize
=============

Syntax
------

     #include <unistd.h>

     int getdtablesize(void);

Description
-----------

Get the maximum number of open file descriptors the system supports.

Return Value
------------

255

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: getegid,  Next: getenv,  Prev: getdtablesize,  Up: Alphabetical List

getegid
=======

Syntax
------

     #include <unistd.h>

     int getegid(void);

Description
-----------

Get the effective group id.

Return Value
------------

42

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: getenv,  Next: geteuid,  Prev: getegid,  Up: Alphabetical List

getenv
======

Syntax
------

     #include <stdlib.h>

     char *getenv(const char *name);

Description
-----------

Get the setting of the environment variable NAME.  Do not alter or free
the returned value.

Return Value
------------

The value, or `NULL' if that variable does not exist.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     char *term = getenv("TERM");


File: libc.info,  Node: geteuid,  Next: getftime,  Prev: getenv,  Up: Alphabetical List

geteuid
=======

Syntax
------

     #include <unistd.h>

     int geteuid(void);

Description
-----------

Gets the effective UID.

Return Value
------------

42

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: getftime,  Next: getgid,  Prev: geteuid,  Up: Alphabetical List

getftime
========

Syntax
------

     #include <dos.h>

     int getftime(int handle, struct ftime *ptr);

Description
-----------

Get the timestamp for the given file handle.  The return structure is as
follows:

     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 */
     }

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     struct ftime t;
     getftime(fd, &t);


File: libc.info,  Node: getgid,  Next: getgrent,  Prev: getftime,  Up: Alphabetical List

getgid
======

Syntax
------

     #include <unistd.h>

     int getgid(void);

Description
-----------

Get the current group id.

Return Value
------------

42

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: getgrent,  Next: getgrgid,  Prev: getgid,  Up: Alphabetical List

getgrent
========

Syntax
------

     #include <grp.h>

     struct group *getgrent(void);

Description
-----------

This function returns the next available group entry.  Note that for
MS-DOS, this is simulated.  If the environment variable `GROUP' is set,
that is the name of the only group returned, else the only group is
"dos".  Thus, under DOS, `getgrent' will always fail on the second and
subsequent calls.

The return type of this and related function is as follows:

     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; /* "" */
     };

Return Value
------------

The next structure, or `NULL' at the end of the list.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------


     struct group *g;
     setgrent();
     while ((g = getgrent()) != NULL)
     {
       printf("group %s gid %d\n", g->gr_name, g->gr_gid);
     }
     endgrent();


File: libc.info,  Node: getgrgid,  Next: getgrnam,  Prev: getgrent,  Up: Alphabetical List

getgrgid
========

Syntax
------

     #include <grp.h>

     extern struct group *getgrgid(int gid);

Description
-----------

This function returns the group entry that matches GID.  *Note
getgrent::, for the description of `struct group'.

Return Value
------------

The matching group, or `NULL' if none match.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: getgrnam,  Next: getgroups,  Prev: getgrgid,  Up: Alphabetical List

getgrnam
========

Syntax
------

     #include <grp.h>

     struct group *getgrnam(char *name);

Description
-----------

This function returns the group entry for the group named NAME.  *Note
getgrent::, for the description of `struct group'.

Return Value
------------

The matching group, or `NULL' if none match.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: getgroups,  Next: gethostname,  Prev: getgrnam,  Up: Alphabetical List

getgroups
=========

Syntax
------

     #include <unistd.h>

     int getgroups(int size, gid_t *grouplist);

Description
-----------

This function always returns zero. It exists to assist porting from
Unix.

Return Value
------------

Zero.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: gethostname,  Next: getitimer,  Prev: getgroups,  Up: Alphabetical List

gethostname
===========

Syntax
------

     #include <unistd.h>
     #include <sys/param.h>

     int gethostname (char *buf, int size);

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
`"HOSTNAME"' environment variable, if present, finally defaulting to
`"pc"'.

The call fails if more than SIZE characters are required to specify the
host name.  A buffer size of `MAXGETHOSTNAME' is guaranteed to be
enough.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     char *buf = (char *) malloc (MAXGETHOSTNAME);
     if (buf && 0 == gethostname (buf, MAXGETHOSTNAME))
       printf ("We're on %s\n", buf);
     if (buf) free(buf);


File: libc.info,  Node: getitimer,  Next: getkey,  Prev: gethostname,  Up: Alphabetical List

getitimer
=========

Syntax
------

     #include <sys/time.h>

     int getitimer(int which, struct itimerval *value);

Description
-----------

This function gets the current value of the interval timer specified by
WHICH into structure VALUE.  Variable WHICH can have the value of
`ITIMER_REAL' or `ITIMER_PROF'.  *Note setitimer::, for more details
about timers.

Upon return, the `it_value' member of 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 `setitimer'.  The `it_interval'
member will hold the interval between two successive alarms as set by
the last call to `setitimer' (but note that interval values less than
the system clock granularity are rounded up to that granularity).  The
value returned in `it_interval' member is _not_ set to zero when the
timer is stopped, it always retains the interval that was last in use.

Return Value
------------

Returns 0 on success, -1 on failure (and sets `errno').

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: getkey,  Next: getlogin,  Prev: getitimer,  Up: Alphabetical List

getkey
======

Syntax
------

     #include <pc.h>
     #include <keys.h>

     int getkey(void);

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 `keys.h' has symbolic names for many of the keys.

*Note getxkey::.

Return Value
------------

The key pressed.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     while (getkey() != K_Alt_3)
       do_something();


File: libc.info,  Node: getlogin,  Next: getlongpass,  Prev: getkey,  Up: Alphabetical List

getlogin
========

Syntax
------

     #include <unistd.h>

     char *getlogin(void);

Description
-----------

Get the login ID of the user.

Return Value
------------

Returns the value of the `USERNAME' environment variable if it is
defined, else the `LOGNAME' environment variable, else the `USER'
environment variable, else `"dosuser"'.

`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 `DJGPP.ENV' defines `USER' with the value
`"dosuser"'.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     printf("I am %s\n", getlogin());


File: libc.info,  Node: getlongpass,  Next: getmntent,  Prev: getlogin,  Up: Alphabetical List

getlongpass
===========

Syntax
------

     #include <stdlib.h>

     int  getlongpass(const char *prompt, char *password, int max_length)

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 PROMPT.  It puts a null-terminated string of at
most MAX_LENGTH - 1 first characters typed by the user into a buffer
pointed to by PASSWORD.  Pressing Ctrl-C or Ctrl-Break will cause the
calling program to `exit(1)'.

Return Value
------------

Zero if successful, -1 on error (and `errno' is set to an appropriate
value).

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     char password[MAX_PASS];

     (void)getlongpass("Password: ", password, MAX_PASS);


File: libc.info,  Node: getmntent,  Next: getopt,  Prev: getlongpass,  Up: Alphabetical List

getmntent
=========

Syntax
------

     #include <mntent.h>

     struct mntent *getmntent(FILE *filep);

Description
-----------

This function returns information about the various drives that are
available to your program.  Beginning with drive `A:', information is
retrieved for successive drives with successive calls to `getmntent'.
Note that drives `A:' and `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 `A:/' or `B:/', depending on how it was last referenced (and
if there is a disk in the drive).

The argument FILEP should be a `FILE*' pointer returned by `setmntent'
(*note setmntent::).

For each drive scanned, a pointer to a static structure of the following
type is returned:

     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 */
     };

DJGPP implementation returns the following in the first 4 fields of
`struct mntent':

`mnt_fsname'
     For networked and CD-ROM drives, this is the name of root
     directory in the form `\\HOST\PATH' (this is called a "UNC name").

     For drives compressed with DoubleSpace, `mnt_fsname' is the string
     `X:\DBLSPACE.NNN', where X is the drive letter of the host drive
     and NNN is the sequence number of the Compressed Volume File.

     For drives compressed with Stacker, `mnt_fsname' is the string
     `X:\STACVOL.NNN', where X and NNN are as for DoubleSpace drives.

     For drives compressed with Jam (a shareware disk compression
     software), `mnt_fsname' is the full name of the Jam archive file.

     For SUBSTed drives, `mnt_fsname' is the actual directory name that
     that was SUBSTed to emulate a drive.

     JOINed drives get their `mnt_fsname' as if they were NOT JOINed
     (i.e., either the label name or the default `Drive X:').

     For drives with a volume label, `mnt_fsname' is the name of the
     label; otherwise the string `Drive X:', where X is the drive
     letter.

`mnt_dir'
     For most drives, this is the name of its root directory `X:/'
     (where X is the drive letter), except that JOINed drives get
     `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 `a:/' or `b:/'), the mount directory will be returned as one
     of these, depending on which drive letter was last used to
     reference that drive.

`mnt_type'
           "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

`mnt_opts'
     The string `ro,dev=XX' for CD-ROM drives, `rw,dev=XX' for all the
     others, where XX is the hexadecimal drive number of the REAL drive
     on which this filesystem resides.  That is, if you call `stat' on
     MNT_FSNAME, you will get the numeric equivalent of XX in `st_dev'
     member of `struct stat'.  E.g., for drive `C:' you will get
     `rw,dev=02'.  Note that SUBSTed and JOINed drives get the drive
     numbers as if SUBST and JOIN were *not* in effect.


Return Value
------------

This function returns a pointer to a `struct mntent', or `NULL' if
there are no more drives to report on.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: getopt,  Next: getpagesize,  Prev: getmntent,  Up: Alphabetical List

getopt
======

Syntax
------

     #include <unistd.h>

     int getopt(int argc, char * const *argv, const char *options);
     extern char *optarg;
     extern int optind, opterr, optopt;

Description
-----------

Parse options from the command line.  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 `optarg' to the argument (if
the switch takes one), sets `optind' to the index in ARGV that it is
using, sets `optopt' to the option letter found, and returns the option
letter found.

If an unexpected option is found, a question mark (`?') is returned.
If an option argument is missing, a colon (`:') is returned if the
first character in OPTIONS is a colon, otherwise a question mark is
returned.  In both cases, if `opterr' is nonzero and the first character
in OPTIONS is not a colon, an error message is printed to `stderr'.

The example below shows how `?' 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.

Return Value
------------

The option character is returned when found.  -1 is returned when there
are no more options.  A colon (`:') is returned when an option argument
is missing and the first character in OPTIONS is a colon.  A question
mark (`?') is returned when an invalid option is found or an option
argument is missing and the first character in OPTIONS is not a colon.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

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);
          }
       }
     }


File: libc.info,  Node: getpagesize,  Next: getpass,  Prev: getopt,  Up: Alphabetical List

getpagesize
===========

Syntax
------

     #include <unistd.h>

     int getpagesize(void);

Description
-----------

Return the size of the native virtual memory page size.

Return Value
------------

4096 for the i386 and higher processors.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: getpass,  Next: getpgrp,  Prev: getpagesize,  Up: Alphabetical List

getpass
=======

Syntax
------

     #include <stdlib.h>

     char * getpass(const char *prompt)

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 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 `exit(1)'.

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.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     char *password = getpass("Password: ");


File: libc.info,  Node: getpgrp,  Next: getpid,  Prev: getpass,  Up: Alphabetical List

getpgrp
=======

Syntax
------

     #include <unistd.h>

     int getpgrp(void);

Description
-----------

Gets the process group, which is currently the same as the pid.

Return Value
------------

The process group.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: getpid,  Next: getppid,  Prev: getpgrp,  Up: Alphabetical List

getpid
======

Syntax
------

     #include <unistd.h>

     int getpid(void);

Description
-----------

Get the process ID, which uniquely identifies each program running on
the system.

Return Value
------------

The process ID.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: getppid,  Next: getpwent,  Prev: getpid,  Up: Alphabetical List

getppid
=======

Syntax
------

     #include <unistd.h>

     int getppid(void);

Description
-----------

Get the parent process ID.  Currently this is always 1, indicating that
the parent process is no longer running.

Return Value
------------

The parent process ID.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: getpwent,  Next: getpwnam,  Prev: getppid,  Up: Alphabetical List

getpwent
========

Syntax
------

     #include <pwd.h>

     struct passwd *getpwent(void);

Description
-----------

This function retrieves the next available password file entry.  For
MS-DOS, this is simulated by providing exactly one entry:

     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;  /* "" */
     };

The `pw_name' and `pw_gecos' members are returned as described under
`getlogin' (*note getlogin::).  The `pw_uid' member is returned as
described under `getuid' (*note getuid::).  `pw_gid' is returned as
described under `getgid' (*note getgid::).  The `pw_passwd' member is
set to the empty string.  The `pw_dir' member is set to the value of
the environment variable `HOME' if it is defined, or to `/' otherwise.
`pw_shell' is set as follows:

   * If the environment variable `SHELL' is set, the value of `SHELL'.

   * If `SHELL' is not set, but the environment variable `COMSPEC' is,
     the value of `COMSPEC'.

   * If neither of the above variables is defined, `pw_shell' is set to
     `"sh"'.

Return Value
------------

The next passwd entry, or `NULL' if there are no more.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     struct passwd *p;
     setpwent();
     while ((p = getpwent()) != NULL)
     {
       printf("user %s name %s\n", p->pw_name, p->pw_gecos);
     }
     endpwent();


File: libc.info,  Node: getpwnam,  Next: getpwuid,  Prev: getpwent,  Up: Alphabetical List

getpwnam
========

Syntax
------

     #include <pwd.h>

     struct passwd *getpwnam(const char *name);

Description
-----------

This function gets the password file entry matching NAME.  See *Note
getpwent::, for the description of `struct passwd'.

Return Value
------------

The matching record, or `NULL' if none match.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: getpwuid,  Next: getrlimit,  Prev: getpwnam,  Up: Alphabetical List

getpwuid
========

Syntax
------

     #include <pwd.h>

     struct passwd *getpwuid(uid_t uid);

Description
-----------

This function gets the password file entry matching UID.  See *Note
getpwent::, for the description of `struct passwd'.

Return Value
------------

The matching record, or `NULL' if none match.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: getrlimit,  Next: getrusage,  Prev: getpwuid,  Up: Alphabetical List

getrlimit
=========

Syntax
------

     #include <sys/resource.h>

     int getrlimit (int rltype, struct rlimit *rlimitp);

Description
-----------

This function gets the resource limit specified by RLTYPE and stores it
in the buffer pointed to by RLIMITP.  The `rlimit' structure is defined
on `sys/resource.h' as follows:

     struct rlimit {
       rlim_t rlim_cur;  /* current (soft) limit */
       rlim_t rlim_max;  /* maximum value for rlim_cur */
     };

The following resource types can be passed in RLTYPE:

`RLIMIT_CPU'
     CPU time in milliseconds.

`RLIMIT_FSIZE'
     Maximum file size.

`RLIMIT_DATA'
     Data size.

`RLIMIT_STACK'
     Stack size.

`RLIMIT_CORE'
     Core file size.

`RLIMIT_RSS'
     Resident set size.

`RLIMIT_MEMLOCK'
     Locked-in-memory address space.

`RLIMIT_NPROC'
     Number of processes.

`RLIMIT_NOFILE'
     Number of open files.

Currently, only the `RLIMIT_STACK' and `RLIMIT_NOFILE' are meaningful:
the first returns the value of `_stklen' (*note _stklen::), the second
the value returned by `sysconf(_SC_OPEN_MAX)' (*note sysconf::).  All
other members of the `rlimit' structure are set to `RLIM_INFINITY',
defined in `sys/resource.h' as `2^31 - 1'.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     struct rlimit rlimitbuf;
     int rc = getrlimit (RLIMIT_STACK, &rlimitbuf);


File: libc.info,  Node: getrusage,  Next: gets,  Prev: getrlimit,  Up: Alphabetical List

getrusage
=========

Syntax
------

     #include <sys/time.h>
     #include <sys/resource.h>

     int getrusage(int who, struct rusage *rusage);

Description
-----------

This function returns information about the running process.  The
structure `struct rusage' is defined on `<sys/resource.h>' as follows:

       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 */
       };

Currently, the only field that is computed is `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 WHO parameter must be `RUSAGE_SELF' or `RUSAGE_CHILDREN'.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     struct rusage r;
     getrusage(RUSAGE_SELF, &r);


File: libc.info,  Node: gets,  Next: gettext,  Prev: getrusage,  Up: Alphabetical List

gets
====

Syntax
------

     #include <stdio.h>

     char *gets(char *buffer);

Description
-----------

Reads characters from `stdin', storing them in BUFFER, until either end
of file or a newline is encountered.  If any characters were stored,
the BUFFER is then `NULL' terminated and its address is returned, else
`NULL' is returned.

Return Value
------------

The address of the buffer, or `NULL'.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     char buf[1000];
     while (gets(buf))
       puts(buf);


File: libc.info,  Node: gettext,  Next: gettextinfo,  Prev: gets,  Up: Alphabetical List

gettext
=======

Syntax
------

     #include <conio.h>

     int     gettext(int _left, int _top, int _right, int _bottom,
                     void *_destin);

Description
-----------

Retrieve a block of screen characters into a buffer.  `gettext' is a
macro defined in `conio.h' that will expand into `_conio_gettext'
(*note _conio_gettext::). This is needed to resolve the name conflict
existing between the `gettext' function from `libintl.a' defined in
`libintl.h' and this one defined in `conio.h'.  If you want to use both
`gettext' functions in the same source file you must use
`_conio_gettext' (*note _conio_gettext::) to get the `gettext' function
from `conio.h'.  This means that if both headers are included in the
same source file the `gettext' keyword will always be reserved for the
`gettext' function defined in `libintl.h' and indeed will always make
reference to the `gettext' function from `libintl.a'.

Return Value
------------

1

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: gettextinfo,  Next: gettime,  Prev: gettext,  Up: Alphabetical List

gettextinfo
===========

Syntax
------

     #include <conio.h>

     void    gettextinfo(struct text_info *_r);

Description
-----------

This function returns the parameters of the current window on the
screen.  The return structure is this:

     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;
     };

The `normattr' field is the text attribute which was in effect before
the program started.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: gettime,  Next: gettimeofday,  Prev: gettextinfo,  Up: Alphabetical List

gettime
=======

Syntax
------

     #include <dos.h>

     void gettime(struct time *);

Description
-----------

This function gets the current time.  The return structure is as
follows:

     struct time {
       unsigned char ti_min;
       unsigned char ti_hour;
       unsigned char ti_hund;
       unsigned char ti_sec;
     };

*Note settime::. *Note getdate::.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     struct time t;
     gettime(&t);


File: libc.info,  Node: gettimeofday,  Next: getuid,  Prev: gettime,  Up: Alphabetical List

gettimeofday
============

Syntax
------

     #include <time.h>

     int gettimeofday(struct timeval *tp, struct timezone *tzp);

Description
-----------

Gets the current GMT time and the local timezone information.  The
return structures are as follows:

     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 */
     };

If either TP or TZP are `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().

*Note settimeofday::.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: getuid,  Next: getw,  Prev: gettimeofday,  Up: Alphabetical List

getuid
======

Syntax
------

     #include <unistd.h>

     int getuid(void);

Description
-----------

Returns the user ID.

Return Value
------------

42

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: getw,  Next: getwd,  Prev: getuid,  Up: Alphabetical List

getw
====

Syntax
------

     #include <stdio.h>

     int getw(FILE *file);

Description
-----------

Reads a single 32-bit binary word in native format from FILE.  This
function is provided for compatibility with other 32-bit environments,
so it reads a 32-bit `int', not a 16-bit `short', like some 16-bit DOS
compilers do.

*Note putw::.

Return Value
------------

The value read, or `EOF' for end-of-file or error.  Since `EOF' is a
valid integer, you should use `feof' or `ferror' to detect this
situation.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     int i = getw(stdin);


File: libc.info,  Node: getwd,  Next: getxkey,  Prev: getw,  Up: Alphabetical List

getwd
=====

Syntax
------

     #include <unistd.h>

     char *getwd(char *buffer);

Description
-----------

Get the current directory and put it in BUFFER.  The return value
includes the drive specifier.

Return Value
------------

BUFFER is returned.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     char buf[PATH_MAX];
     getwd(buf);


File: libc.info,  Node: getxkey,  Next: glob,  Prev: getwd,  Up: Alphabetical List

getxkey
=======

Syntax
------

     #include <pc.h>
     #include <keys.h>

     int getxkey(void);

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 `keys.h' has symbolic names for many of the keys.

*Note getkey::.

Return Value
------------

The key pressed.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     while (getxkey() != K_EEnd)
       do_something();


File: libc.info,  Node: glob,  Next: globfree,  Prev: getxkey,  Up: Alphabetical List

glob
====

Syntax
------

     #include <glob.h>

     int  glob(const char *pattern, int flags,
               int (*errfunc)(const char *epath, int eerrno), glob_t *pglob);

Description
-----------

This function expands a filename wildcard which is passed as PATTERN.
The pattern may include these special characters:

`*'
     Matches zero of more characters.

`?'
     Matches exactly one character (any character).

`[...]'
     Matches one character from a group of characters.  If the first
     character is `!', matches any character _not_ in the group.  A
     group is defined as a list of characters between the brackets,
     e.g. `[dkl_]', or by two characters separated by `-' to indicate
     all characters between and including these two.  For example,
     `[a-d]' matches `a', `b', `c', or `d', and `[!a-zA-Z0-9]' matches
     any character that is not alphanumeric.

`...'
     Matches all the subdirectories, recursively (VMS aficionados,
     rejoice!).

`\'
     Causes the next character to not be treated as special.  For
     example, `\[' matches a literal `['.  If FLAGS includes
     `GLOB_NOESCAPE', this quoting is disabled and `\' is handled as a
     simple character.


The variable FLAGS controls certain options of the expansion process.
Possible values for FLAGS are as follows:

`GLOB_APPEND'
     Append the matches to those already present in the array
     `pglob->gl_pathv'.  By default, `glob' discards all previous
     contents of `pglob->gl_pathv' and allocates a new memory block for
     it.  If you use `GLOB_APPEND', `pglob' should point to a structure
     returned by a previous call to `glob'.

`GLOB_DOOFFS'
     Skip `pglob->gl_offs' entries in `gl_pathv' and put new matches
     after that point.  By default, `glob' puts the new matches
     beginning at `pglob->gl_pathv[0]'.  You can use this flag both with
     `GLOB_APPEND' (in which case the new matches will be put after the
     first `pglob->gl_offs' matches from previous call to `glob'), or
     without it (in which case the first `pglob->gl_offs' entries in
     `pglob->gl_pathv' will be filled by `NULL' pointers).

`GLOB_ERR'
     Stop when an unreadable directory is encountered and call
     user-defined function ERRFUNC.  This cannot happen under DOS (and
     thus ERRFUNC is never used).

`GLOB_MARK'
     Append a slash to each pathname that is a directory.

`GLOB_NOCHECK'
     If no matches are found, return the pattern itself as the only
     match.  By default, `glob' doesn't change `pglob' if no matches are
     found.

`GLOB_NOESCAPE'
     Disable blackslash as an escape character.  By default, backslash
     quotes special meta-characters in wildcards described above.

`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.


Given the pattern and the flags, `glob' expands the pattern and returns
a list of files that match the pattern in a structure a pointer to
which is passed via PGLOB.  This structure is like this:

     typedef struct {
       size_t gl_pathc;
       char **gl_pathv;
       size_t gl_offs;
     } glob_t;

In the structure, the `gl_pathc' field holds the number of filenames in
`gl_pathv' list; this includes the filenames produced by this call,
plus any previous filenames if `GLOB_APPEND' or `GLOB_DOOFFS' were set
in FLAGS.  The list of matches is returned as an array of pointers to
the filenames; `gl_pathv' holds the address of the array.  Thus, the
filenames which match the pattern can be accessed as `gl_pathv[0]',
`gl_pathv[1]', etc.  If `GLOB_DOOFFS' was set in FLAGS, the new matches
begin at offset given by `gl_offs'.

`glob' allocates memory to hold the filenames.  This memory should be
freed by calling `globfree' (*note globfree::).

Return Value
------------

Zero on success, or one of these codes:

`GLOB_ABORTED'
     Not used in DJGPP implementation.

`GLOB_NOMATCH'
     No files matched the given pattern.

`GLOB_NOSPACE'
     Not enough memory to accommodate expanded filenames.

`GLOB_ERR'
     Never happens on MSDOS, see above.


Notes
-----

`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 `LFN' is set to `n', `glob' behaves on
Windows 9x exactly as it does on MSDOS.

Setting the environment variable `FNCASE' to `y', or setting the
`_CRT0_FLAG_PRESERVE_FILENAME_CASE' bit in the `_crt0_startup_flags'
variable (*note _crt0_startup_flags::) suppresses any letter-case
conversions in filenames and forces case-sensitive filename matching.
*Note _preserve_fncase::.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

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;
     }


File: libc.info,  Node: globfree,  Next: gmtime,  Prev: glob,  Up: Alphabetical List

globfree
========

Syntax
------

     #include <glob.h>

     void globfree(glob_t *pglob);

Description
-----------

Frees the memory associated with PGLOB, which should have been
allocated by a call to `glob' (*note glob::).

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: gmtime,  Next: gmtime_r,  Prev: globfree,  Up: Alphabetical List

gmtime
======

Syntax
------

     #include <time.h>

     struct tm *gmtime(const time_t *tod);

Description
-----------

Converts the time represented by TOD into a structure.

The return structure has this format:

     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 */
     };

The structure pointed to is static and will be overwritten with each
call to `gmtime'.  The structure should be copied if it needs to be
preserved.  *Note gmtime_r::, for an alternate interface that allows
the caller to provide the structure to be filled.

*Note localtime::, for a similar function that returns the information
corrected for the local time zone instead of GMT.

Return Value
------------

A pointer to a static structure which is overwritten with each call.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     time_t x;
     struct tm *t;
     time(&x);
     t = gmtime(&x);


File: libc.info,  Node: gmtime_r,  Next: _go32_conventional_mem_selector,  Prev: gmtime,  Up: Alphabetical List

gmtime_r
========

Syntax
------

     #include <time.h>

     struct tm *gmtime_r(const time_t * restrict tod, struct tm * restrict tptr);

Description
-----------

Converts the time represented by TOD into a broken down calendar time
structure TPTR.

*Note gmtime::, for a description of type `struct tm'.

*Note gmtime::, for an alternate ISO Standard interface.

*Note localtime_r::, for a similar function that returns the information
corrected for the local time zone instead of GMT.

Return Value
------------

A pointer to TPTR containing the broken down calendar time.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     time_t x;
     struct tm *t;
     struct tm tm;
     time(&x);
     t = gmtime_r(&x, &tm);


File: libc.info,  Node: _go32_conventional_mem_selector,  Next: _go32_dpmi_allocate_dos_memory,  Prev: gmtime_r,  Up: Alphabetical List

_go32_conventional_mem_selector
===============================

Syntax
------

     #include <go32.h>

     u_short _go32_conventional_mem_selector();

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 `movedata' (*note movedata::) to
manipulate memory in the conventional address space.

Return Value
------------

The selector.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: _go32_dpmi_allocate_dos_memory,  Next: _go32_dpmi_allocate_iret_wrapper,  Prev: _go32_conventional_mem_selector,  Up: Alphabetical List

_go32_dpmi_allocate_dos_memory
==============================

Syntax
------

     #include <dpmi.h>

     int _go32_dpmi_allocate_dos_memory(_go32_dpmi_seginfo *info);

Description
-----------

*Note DPMI Overview::.

Allocate a part of the conventional memory area (the first 640K).  Set
the `size' field of INFO to the number of paragraphs requested (this is
(size in bytes + 15)/16), then call.  The `rm_segment' field of INFO
contains the segment of the allocated memory.

The memory may be resized with `_go32_dpmi_resize_dos_memory' and must
be freed with `_go32_dpmi_free_dos_memory'.

If there isn't enough memory in the system, the `size' field of INFO
has the largest available size, and an error is returned.

See also *Note dosmemput::, and *Note dosmemget::.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: _go32_dpmi_allocate_iret_wrapper,  Next: _go32_dpmi_allocate_real_mode_callback_iret,  Prev: _go32_dpmi_allocate_dos_memory,  Up: Alphabetical List

_go32_dpmi_allocate_iret_wrapper
================================

Syntax
------

     #include <dpmi.h>

     int _go32_dpmi_allocate_iret_wrapper(_go32_dpmi_seginfo *info);

Description
-----------

*Note 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 `pm_offset' field of INFO and call this
function.  The `pm_field' will get replaced with the address of the
wrapper function, which you pass to both
`_go32_dpmi_set_protected_mode_interrupt_vector' and
`_go32_dpmi_free_iret_wrapper'.

*Warning!* Because of the way DPMI works, you may _not_ `longjmp' out
of an interrupt handler or perform any system calls (such as `printf')
from within an interrupt handler.

Do not enable interrupts with `enable()' or `asm("sti")' in your
function.

See also *Note _go32_dpmi_set_protected_mode_interrupt_vector::, and
*Note _go32_dpmi_free_iret_wrapper::.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);
     ...
     _go32_dpmi_free_iret_wrapper(&info);


File: libc.info,  Node: _go32_dpmi_allocate_real_mode_callback_iret,  Next: _go32_dpmi_allocate_real_mode_callback_retf,  Prev: _go32_dpmi_allocate_iret_wrapper,  Up: Alphabetical List

_go32_dpmi_allocate_real_mode_callback_iret
===========================================

Syntax
------

     #include <dpmi.h>

     int _go32_dpmi_allocate_real_mode_callback_iret(
             _go32_dpmi_seginfo *info, _go32_dpmi_registers *regs
     );

Description
-----------

*Note DPMI Overview::.

This function allocates a "real-mode callback".  Fill in the
`pm_offset' field of INFO and call this function.  It will fill in the
`rm_segment' and `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 REGS, which should be a global, and will be
passed to your function.  Any changes in REGS will be reflected back
into real mode.  A wrapper will be added to your function to simulate
the effects of an `iret' instruction, so this function is useful for
trapping real-mode software interrupts (like 0x1b - `Ctrl-<Break>' hit).

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);
     }


File: libc.info,  Node: _go32_dpmi_allocate_real_mode_callback_retf,  Next: _go32_dpmi_chain_protected_mode_interrupt_vector,  Prev: _go32_dpmi_allocate_real_mode_callback_iret,  Up: Alphabetical List

_go32_dpmi_allocate_real_mode_callback_retf
===========================================

Syntax
------

     #include <dpmi.h>

     int _go32_dpmi_allocate_real_mode_callback_retf(
             _go32_dpmi_seginfo *info, _go32_dpmi_registers *regs
     );

Description
-----------

*Note DPMI Overview::.

This function allocates a "real-mode callback".  Fill in the
`pm_offset' field of INFO and call this function.  It will fill in the
`rm_segment' and `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 REGS, which should be a global, and will be
passed to your function.  Any changes in 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.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

*Note _go32_dpmi_allocate_real_mode_callback_iret::, for an example of
usage.


File: libc.info,  Node: _go32_dpmi_chain_protected_mode_interrupt_vector,  Next: _go32_dpmi_free_dos_memory,  Prev: _go32_dpmi_allocate_real_mode_callback_retf,  Up: Alphabetical List

_go32_dpmi_chain_protected_mode_interrupt_vector
================================================

Syntax
------

     #include <dpmi.h>

     int _go32_dpmi_chain_protected_mode_interrupt_vector(
             int vector, _go32_dpmi_seginfo *info
     );

Description
-----------

*Note 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.

*Warning!* Because of the way DPMI works, you may _not_ `longjmp' out
of an interrupt handler or perform any system calls (such as `printf')
from within an interrupt handler.

Do not enable interrupts with `enable()' or `asm("sti")' in your
function.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

*Note _go32_dpmi_set_protected_mode_interrupt_vector::.


File: libc.info,  Node: _go32_dpmi_free_dos_memory,  Next: _go32_dpmi_free_iret_wrapper,  Prev: _go32_dpmi_chain_protected_mode_interrupt_vector,  Up: Alphabetical List

_go32_dpmi_free_dos_memory
==========================

Syntax
------

     #include <dpmi.h>

     int _go32_dpmi_free_dos_memory(_go32_dpmi_seginfo *info);

Description
-----------

*Note DPMI Overview::.

This function frees the conventional memory allocated by
`_go32_dpmi_allocate_real_mode_memory'.  You should pass it the same
structure as was used to allocate it.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     _go32_dpmi_seginfo info;
     info.size = 100;
     _go32_dpmi_allocate_dos_memory(&info);
     _go32_dpmi_free_dos_memory(&info);


File: libc.info,  Node: _go32_dpmi_free_iret_wrapper,  Next: _go32_dpmi_free_real_mode_callback,  Prev: _go32_dpmi_free_dos_memory,  Up: Alphabetical List

_go32_dpmi_free_iret_wrapper
============================

Syntax
------

     #include <dpmi.h>

     int _go32_dpmi_free_iret_wrapper(_go32_dpmi_seginfo *info);

Description
-----------

*Note DPMI Overview::.

This function frees the memory used by the wrapper created by
`_go32_dpmi_allocate_iret_wrapper'.  You should not free a wrapper that
is still in use.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

*Note _go32_dpmi_allocate_iret_wrapper::.


File: libc.info,  Node: _go32_dpmi_free_real_mode_callback,  Next: _go32_dpmi_get_free_memory_information,  Prev: _go32_dpmi_free_iret_wrapper,  Up: Alphabetical List

_go32_dpmi_free_real_mode_callback
==================================

Syntax
------

     #include <dpmi.h>

     int _go32_dpmi_free_real_mode_callback(_go32_dpmi_seginfo *info);

Description
-----------

*Note DPMI Overview::.

This function frees the real-mode callbacks and wrappers allocated by
`_go32_dpmi_allocate_real_mode_callback_iret' and
`_go32_dpmi_allocate_real_mode_callback_retf'.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

*Note _go32_dpmi_allocate_real_mode_callback_iret::, for an example of
usage.


File: libc.info,  Node: _go32_dpmi_get_free_memory_information,  Next: _go32_dpmi_get_protected_mode_interrupt_vector,  Prev: _go32_dpmi_free_real_mode_callback,  Up: Alphabetical List

_go32_dpmi_get_free_memory_information
======================================

Syntax
------

     #include <dpmi.h

     int _go32_dpmi_get_free_memory_information(_go32_dpmi_meminfo *info);

Description
-----------

This function fills in the following structure:

     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;

The only field that is guaranteed to have useful data is
`available_memory'.  Any unavailable field has -1 in it.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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;
     }


File: libc.info,  Node: _go32_dpmi_get_protected_mode_interrupt_vector,  Next: _go32_dpmi_get_real_mode_interrupt_vector,  Prev: _go32_dpmi_get_free_memory_information,  Up: Alphabetical List

_go32_dpmi_get_protected_mode_interrupt_vector
==============================================

Syntax
------

     #include <dpmi.h>

     int _go32_dpmi_get_protected_mode_interrupt_vector(
             int vector, _go32_dpmi_seginfo *info
     );

Description
-----------

*Note DPMI Overview::.

This function puts the selector and offset of the specified interrupt
vector into the `pm_selector' and `pm_offset' fields of INFO.  This
structure can be saved and later passed to
`_go32_dpmi_set_protected_mode_interrupt_vector' to restore a vector.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

*Note _go32_dpmi_set_protected_mode_interrupt_vector::, for an example
of usage.


File: libc.info,  Node: _go32_dpmi_get_real_mode_interrupt_vector,  Next: _go32_dpmi_lock_code,  Prev: _go32_dpmi_get_protected_mode_interrupt_vector,  Up: Alphabetical List

_go32_dpmi_get_real_mode_interrupt_vector
=========================================

Syntax
------

     #include <dpmi.h>

     int _go32_dpmi_get_real_mode_interrupt_vector(
             int vector, _go32_dpmi_seginfo *info
     );

Description
-----------

*Note DPMI Overview::.

This function gets the real-mode interrupt vector specified into the
address in the `rm_segment' and `rm_offset' fields in INFO.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

*Note _go32_dpmi_allocate_real_mode_callback_iret::, for an example of
usage.


File: libc.info,  Node: _go32_dpmi_lock_code,  Next: _go32_dpmi_lock_data,  Prev: _go32_dpmi_get_real_mode_interrupt_vector,  Up: Alphabetical List

_go32_dpmi_lock_code
====================

Syntax
------

     #include <dpmi.h>

     int _go32_dpmi_lock_code( void *lockaddr, unsigned long locksize);

Description
-----------

Locks the given region of code, starting at LOCKADDR for LOCKSIZE
bytes.  LOCKADDR is a regular pointer in your program, such as the
address of a function.

Return Value
------------

0 if success, -1 if failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------


     void my_handler()
     {
     }

     void lock_my_handler()
     {
       _go32_dpmi_lock_code(my_handler,
                            (unsigned long)(lock_my_handler - my_handler));
     }


File: libc.info,  Node: _go32_dpmi_lock_data,  Next: _go32_dpmi_remaining_physical_memory,  Prev: _go32_dpmi_lock_code,  Up: Alphabetical List

_go32_dpmi_lock_data
====================

Syntax
------

     #include <dpmi.h>

     int _go32_dpmi_lock_data( void *lockaddr, unsigned long locksize);

Description
-----------

Locks the given region of data, starting at LOCKADDR for LOCKSIZE
bytes.  LOCKADDR is a regular pointer in your program, such as the
address of a variable.

Return Value
------------

0 if success, -1 if failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------


     int semaphore=0;

     void lock_my_handler()
     {
       _go32_dpmi_lock_data(&semaphore, 4);
     }


File: libc.info,  Node: _go32_dpmi_remaining_physical_memory,  Next: _go32_dpmi_remaining_virtual_memory,  Prev: _go32_dpmi_lock_data,  Up: Alphabetical List

_go32_dpmi_remaining_physical_memory
====================================

Syntax
------

     #include <dpmi.h>

     unsigned long _go32_dpmi_remaining_physical_memory(void);

Description
-----------

Returns the amount of physical memory that is still available in the
system.

Return Value
------------

The amount in bytes.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _go32_dpmi_remaining_virtual_memory,  Next: _go32_dpmi_resize_dos_memory,  Prev: _go32_dpmi_remaining_physical_memory,  Up: Alphabetical List

_go32_dpmi_remaining_virtual_memory
===================================

Syntax
------

     #include <dpmi.h>

     unsigned long _go32_dpmi_remaining_virtual_memory(void);

Description
-----------

Returns the amount of virtual memory that is still available in the
system.

Return Value
------------

The amount in bytes.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _go32_dpmi_resize_dos_memory,  Next: _go32_dpmi_set_protected_mode_interrupt_vector,  Prev: _go32_dpmi_remaining_virtual_memory,  Up: Alphabetical List

_go32_dpmi_resize_dos_memory
============================

Syntax
------

     #include <dpmi.h>

     int _go32_dpmi_resize_dos_memory(_go32_dpmi_seginfo *info);

Description
-----------

*Note DPMI Overview::.

The INFO structure is the same one used to allocate the memory.  Fill
in a new value for `size' and call this function.  If there is not
enough memory to satisfy the request, the largest size is filled in to
the `size' field, the memory is not resized, and this function fails.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: _go32_dpmi_set_protected_mode_interrupt_vector,  Next: _go32_dpmi_set_real_mode_interrupt_vector,  Prev: _go32_dpmi_resize_dos_memory,  Up: Alphabetical List

_go32_dpmi_set_protected_mode_interrupt_vector
==============================================

Syntax
------

     #include <dpmi.h>

     int _go32_dpmi_set_protected_mode_interrupt_vector(
             int vector, _go32_dpmi_seginfo *info
     );

Description
-----------

*Note DPMI Overview::.

This function sets the protected mode interrupt vector specified to
point to the given function.  The `pm_offset' and `pm_selector' fields
of INFO must be filled in (*note _go32_my_cs::).  The following should
be noted:

   *  You may not `longjmp' out of an interrupt handler.

   *  You may not make any function calls that require system calls,
     such as `printf'.

   *  This function will not wrap the handler for you.  The
     `_go32_dpmi_allocate_iret_wrapper' and
     `_go32_dpmi_chain_protected_mode_interrupt_vector' functions can
     wrap your function if you want.

   *  You must set the pm_selector field of INFO.  Use `_go32_my_cs' to
     get a selector valid for your functions.


Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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;
     }


File: libc.info,  Node: _go32_dpmi_set_real_mode_interrupt_vector,  Next: _go32_dpmi_simulate_fcall,  Prev: _go32_dpmi_set_protected_mode_interrupt_vector,  Up: Alphabetical List

_go32_dpmi_set_real_mode_interrupt_vector
=========================================

Syntax
------

     #include <dpmi.h>

     int _go32_dpmi_set_real_mode_interrupt_vector(
             int vector, _go32_dpmi_seginfo *info
     );

Description
-----------

*Note DPMI Overview::.

This function sets the real-mode interrupt vector specified to point to
the address in the `rm_segment' and `rm_offset' fields in INFO.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

*Note _go32_dpmi_allocate_real_mode_callback_iret::, for an example of
usage.


File: libc.info,  Node: _go32_dpmi_simulate_fcall,  Next: _go32_dpmi_simulate_fcall_iret,  Prev: _go32_dpmi_set_real_mode_interrupt_vector,  Up: Alphabetical List

_go32_dpmi_simulate_fcall
=========================

Syntax
------

     #include <dpmi.h>

     int _go32_dpmi_simulate_fcall(_go32_dpmi_registers *regs);

Description
-----------

*Note 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 REGS, including `CS'
and `IP', which indicate the address of the call.  Any registers the
function modifies are reflected in REGS on return.

If `SS' and `SP' are both zero, a small temporary stack is used when in
real mode.  If not, they are used _as is_.  It's a good idea to use
`memset' to initialize the register structure before using it.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: _go32_dpmi_simulate_fcall_iret,  Next: _go32_dpmi_simulate_int,  Prev: _go32_dpmi_simulate_fcall,  Up: Alphabetical List

_go32_dpmi_simulate_fcall_iret
==============================

Syntax
------

     #include <dpmi.h>

     int _go32_dpmi_simulate_fcall_iret(_go32_dpmi_registers *regs);

Description
-----------

*Note DPMI Overview::.

This function simulates a real-mode far call to a function that returns
with an `iret' instruction.  The registers are set up from REGS,
including `CS' and `IP', which indicate the address of the call.  Any
registers the function modifies are reflected in REGS on return.

If `SS' and `SP' are both zero, a small temporary stack is used when in
real mode.  If not, they are used _as is_.  It's a good idea to use
`memset' to initialize the register structure before using it.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: _go32_dpmi_simulate_int,  Next: _go32_info_block,  Prev: _go32_dpmi_simulate_fcall_iret,  Up: Alphabetical List

_go32_dpmi_simulate_int
=======================

Syntax
------

     #include <dpmi.h>

     int _go32_dpmi_simulate_int(int vector, _go32_dpmi_registers *regs);

Description
-----------

*Note DPMI Overview::.

This function simulates a real-mode interrup.  The registers are set up
from REGS, including `CS' and `IP', which indicate the address of the
call.  Any registers the function modifies are reflected in REGS on
return.

If `SS' and `SP' are both zero, a small temporary stack is used when in
real mode.  If not, they are used _as is_.  It's a good idea to use
`memset' to initialize the register structure before using it.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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));


File: libc.info,  Node: _go32_info_block,  Next: _go32_interrupt_stack_size,  Prev: _go32_dpmi_simulate_int,  Up: Alphabetical List

_go32_info_block
================

Syntax
------

     #include <go32.h>

     extern __Go32_Info_Block _go32_info_block;

Description
-----------

The go32 information block is a mechanism for `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 `libc.a' only.

The structure has this format:

     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;

The linear address fields provide values that are suitable for
`dosmemget', `dosmemput', and `movedata'.  The
selector_for_linear_memory is suitable for `<sys/farptr.h>' selector
parameters.

Due to the length of these fields, and their popularity, the following
macros are available:

`_dos_ds'
     This expands to _go32_info_block.selector_for_linear_memory

`__tb'
     This expands to _go32_info_block.linear_address_of_transfer_buffer

`__tb_size'
     This expands to _go32_info_block.size_of_transfer_buffer


The `run_mode' field indicates the mode that the program is running in.
The following modes are defined:

`_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.

`_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.

`_GO32_RUN_MODE_XMS'
     This indicates that the extender is managing the CPU, but an XMS
     driver is managing the memory pool.

`_GO32_RUN_MODE_VCPI'
     This indicates that a VCPI server (like `emm386' or `qemm') is
     managing both the CPU and the memory.

`_GO32_RUN_MODE_DPMI'
     This indicates that a DPMI server (like `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 `run_mode_info' field has the DPMI
     specification version, in hex, shifted eight bits.  For example,
     DPMI 0.9 has 0x005A in the `run_mode_info' field.


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.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     dosmemget(_go32_info_block.linear_address_of_primary_screen,
               80*25*2, buf);


File: libc.info,  Node: _go32_interrupt_stack_size,  Next: _go32_my_cs,  Prev: _go32_info_block,  Up: Alphabetical List

_go32_interrupt_stack_size
==========================

Syntax
------

     #include <dpmi.h>

     extern unsigned long _go32_interrupt_stack_size;

Description
-----------

The default size of the interrupt handler's stack.  Defaults to 32k.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _go32_my_cs,  Next: _go32_my_ds,  Prev: _go32_interrupt_stack_size,  Up: Alphabetical List

_go32_my_cs
===========

Syntax
------

     #include <go32.h>

     u_short _go32_my_cs();

Description
-----------

Returns the current `CS'.  This is useful for setting up interrupt
vectors and such.

Return Value
------------

`CS'

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _go32_my_ds,  Next: _go32_my_ss,  Prev: _go32_my_cs,  Up: Alphabetical List

_go32_my_ds
===========

Syntax
------

     #include <go32.h>

     u_short _go32_my_ds();

Description
-----------

Returns the current `DS'.  This is useful for moving memory and such.

Return Value
------------

`DS'

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _go32_my_ss,  Next: _go32_rmcb_stack_size,  Prev: _go32_my_ds,  Up: Alphabetical List

_go32_my_ss
===========

Syntax
------

     #include <go32.h>

     u_short _go32_my_ss();

Description
-----------

Returns the current `SS'.  This is useful for moving memory and such.

Return Value
------------

`SS'

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _go32_rmcb_stack_size,  Next: _go32_want_ctrl_break,  Prev: _go32_my_ss,  Up: Alphabetical List

_go32_rmcb_stack_size
=====================

Syntax
------

     #include <dpmi.h>

     extern unsigned long _go32_rmcb_stack_size;

Description
-----------

The default size of the real mode callback handler's stack.  Defaults
to 32k.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _go32_want_ctrl_break,  Next: _go32_was_ctrl_break_hit,  Prev: _go32_rmcb_stack_size,  Up: Alphabetical List

_go32_want_ctrl_break
=====================

Syntax
------

     #include <go32.h>

     void   _go32_want_ctrl_break(int yes);

Description
-----------

This function tells go32 whether or not it wants `Ctrl-Break' to be an
exception or passed to the application.  If you pass a nonzero value
for YES, pressing `Ctrl-Break' will set a flag that can be detected
with `_go32_was_ctrl_break_hit' (*note _go32_was_ctrl_break_hit::).  If
you pass zero for YES, when you press `Ctrl-Break' the program will be
terminated.

Note that if you call `_go32_was_ctrl_break_hit', this function
automatically gets called to ask for `Ctrl-Break' events.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     _g32_want_ctrl_break(1);
     do_something_long();
     _g32_want_ctrl_break(0);


File: libc.info,  Node: _go32_was_ctrl_break_hit,  Next: gotoxy,  Prev: _go32_want_ctrl_break,  Up: Alphabetical List

_go32_was_ctrl_break_hit
========================

Syntax
------

     #include <go32.h>

     unsigned _go32_was_ctrl_break_hit(void);

Description
-----------

This function returns the number of times that `Ctrl-Break' was hit
since the last call to this function or `_go32_want_ctrl_break' (*note
_go32_want_ctrl_break::).

Return Value
------------

Zero if `Ctrl-Break' hasn't been hit, nonzero to indicate how many
times if it has been hit.

Note that `_go32_want_ctrl_break' is automatically called to request
these events, so you don't have to set up for this call.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     while (!_go32_was_ctrl_break_hit())
       do_something();


File: libc.info,  Node: gotoxy,  Next: gppconio_init,  Prev: _go32_was_ctrl_break_hit,  Up: Alphabetical List

gotoxy
======

Syntax
------

     #include <conio.h>

     void gotoxy(int x, int y);

Description
-----------

Move the cursor to row y, column x.  The upper left corner of the
current window is (1,1).

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: gppconio_init,  Next: __has_fd_properties,  Prev: gotoxy,  Up: Alphabetical List

gppconio_init
=============

Syntax
------

     #include <conio.h>

     void gppconio_init(void);

Description
-----------

Initialize the screen.  This is called automatically at program start-up
if you use any of the `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.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __has_fd_properties,  Next: _hash2v,  Prev: gppconio_init,  Up: Alphabetical List

__has_fd_properties
===================

Syntax
------

     #include <libc/fd_props.h>

     int __has_fd_properties(int fd);

Description
-----------

This internal function checks whether there are any properties
associated with the file descriptor FD.

Return Value
------------

Non-zero if FD has any properties; zero otherwise.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _hash2v,  Next: hasmntopt,  Prev: __has_fd_properties,  Up: Alphabetical List

_hash2v
=======

Syntax
------

     #include <search.h>

     unsigned long _hash2v(unsigned char *s, unsigned long *v2)

Description
-----------

This function generate two hash values from the string S.  It returns
the first and sets *V2 to the second.

Return Value
------------

The first hash value.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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;
     }


File: libc.info,  Node: hasmntopt,  Next: hcreate,  Prev: _hash2v,  Up: Alphabetical List

hasmntopt
=========

Syntax
------

     #include <mntent.h>

     char *hasmntopt(const struct mntent *mnt, const char *opt);

Description
-----------

This function scans the `mnt_opts' field of the `mntent' structure
pointed to by MNT for a substring that matches OPT.  *Note getmntent::.

Return Value
------------

This function returns the address of the substring if a match is found,
or `NULL' otherwise.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: hcreate,  Next: hdestroy,  Prev: hasmntopt,  Up: Alphabetical List

hcreate
=======

Syntax
------

     #include <search.h>

     int hcreate(size_t nel)

Description
-----------

This function creates a hash table that has room for NEL elements.

There can only be at most one hash table in use at any time.

See also `hdestroy' (*note hdestroy::) and `hsearch' (*note hsearch::).

Return Value
------------

Non-zero if successful, or zero if the hash table couldn't be created.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

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;
     }


File: libc.info,  Node: hdestroy,  Next: highvideo,  Prev: hcreate,  Up: Alphabetical List

hdestroy
========

Syntax
------

     #include <search.h>

     void hdestroy(void)

Description
-----------

This function destroys the hash table previously created by a call to
`hcreate' (*note hcreate::).

See also `hsearch' (*note hsearch::).

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

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;
     }


File: libc.info,  Node: highvideo,  Next: hsearch,  Prev: hdestroy,  Up: Alphabetical List

highvideo
=========

Syntax
------

     #include <conio.h>

     void highvideo(void);

Description
-----------

Causes any new characters put on the screen to be bright.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: hsearch,  Next: htonl,  Prev: highvideo,  Up: Alphabetical List

hsearch
=======

Syntax
------

     #include <search.h>

     ENTRY * hsearch(ENTRY item, ACTION action);

Description
-----------

This function searches the hash table previously created by a call to
`hcreate' (*note hcreate::) for the key ITEM.KEY.  If the key is found
a pointer to that entry is returned.  If the key is not found and
action is ENTER, 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, `NULL' is returned.

The comparison function used is `strcmp'.

The types ACTION and ENTRY are defined as:

     typedef enum {
       FIND,
       ENTER
     } ACTION;

     typedef struct entry {
       char    *key;
       void    *data;
     } ENTRY;

See also `hdestroy' (*note hdestroy::).

Return Value
------------

`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 `NULL', if action is FIND.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

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;
     }


File: libc.info,  Node: htonl,  Next: htons,  Prev: hsearch,  Up: Alphabetical List

htonl
=====

Syntax
------

     #include <netinet/in.h>

     unsigned long htonl(unsigned long val);

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.

Return Value
------------

The network-order value.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     packet.ipaddr = htonl(ip);


File: libc.info,  Node: htons,  Next: hypot,  Prev: htonl,  Up: Alphabetical List

htons
=====

Syntax
------

     #include <netinet/in.h>

     unsigned short htons(unsigned short val);

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.

Return Value
------------

The network-order value.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     tcp.port = htons(port);


File: libc.info,  Node: hypot,  Next: imaxabs,  Prev: htons,  Up: Alphabetical List

hypot
=====

Syntax
------

     #include <math.h>

     double hypot(double x, double y);

Description
-----------

This function computes `sqrt(X*X + Y*Y)', the length of a hypotenuse of
a right triangle whose shorter sides are X and Y.  In other words, it
computes the Euclidean distance between the points `(0,0)' and `(X,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 `sqrt(X*X + Y*Y)' could cause overflow or
underflow for extreme (very large or very small) values of X and Y.

Return Value
------------

The value of `sqrt(X*X + Y*Y)'.  If both arguments are finite, but the
result is so large that it would overflow a `double', the return value
is `Inf', and `errno' is set to `ERANGE'.  If one of the arguments is
`Inf', the return value is `Inf' and the value of `errno' is left
unchanged.  If one of the arguments is `NaN', the return value is `NaN'
and `errno' is set to `EDOM'.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: imaxabs,  Next: imaxdiv,  Prev: hypot,  Up: Alphabetical List

imaxabs
=======

Syntax
------

     #include <inttypes.h>

     intmax_t imaxabs (intmax_t x);

Description
-----------

This function takes the absolute value of X.

`abs' (*note abs::) operates on an `int'.  This function operates on a
greatest-width integer.

Return Value
------------

`|X|'

Portability
-----------

ANSI/ISO C   C99; not C89
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992


File: libc.info,  Node: imaxdiv,  Next: inb,  Prev: imaxabs,  Up: Alphabetical List

imaxdiv
=======

Syntax
------

     #include <inttypes.h>

     imaxdiv_t imaxdiv (intmax_t numerator, intmax_t denominator);

Description
-----------

Returns the quotient and remainder of the division NUMERATOR divided by
DENOMINATOR.  The return type is as follows:

     typedef struct {
       intmax_t quot;
       intmax_t rem;
     } imaxdiv_t;

Return Value
------------

The results of the division are returned.

Portability
-----------

ANSI/ISO C   C99; not C89
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992

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 }


File: libc.info,  Node: inb,  Next: index,  Prev: imaxdiv,  Up: Alphabetical List

inb
===

Syntax
------

     #include <pc.h>

     unsigned char inb(unsigned short _port);

Description
-----------

Calls *Note inportb::. Provided only for compatibility.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: index,  Next: initstate,  Prev: inb,  Up: Alphabetical List

index
=====

Syntax
------

     #include <strings.h>

     char *index(const char *string, int ch);

Description
-----------

Returns a pointer to the first occurrence of CH in STRING.  Note that
the `NULL' character counts, so if you pass zero as CH you'll get a
pointer to the end of the string back.

Return Value
------------

A pointer to the character, or `NULL' if it wasn't found.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     if (index(path, '*'))
       do_wildcards(path);


File: libc.info,  Node: initstate,  Next: inp,  Prev: index,  Up: Alphabetical List

initstate
=========

Syntax
------

     #include <stdlib.h>

     char *initstate(unsigned seed, char *arg_state, int n);

Description
-----------

Initializes the random number generator (*note random::) with pointer
ARG_STATE to array of N bytes, then calls `srandom' with SEED.

Return Value
------------

Pointer to old state information.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: inp,  Next: inportb,  Prev: initstate,  Up: Alphabetical List

inp
===

Syntax
------

     #include <pc.h>

     unsigned char inp(unsigned short _port);

Description
-----------

Calls *Note inportb::.  Provided only for compatibility.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: inportb,  Next: inportl,  Prev: inp,  Up: Alphabetical List

inportb
=======

Syntax
------

     #include <pc.h>

     unsigned char inportb(unsigned short _port);

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.

Return Value
------------

The value returned through the port.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: inportl,  Next: inportsb,  Prev: inportb,  Up: Alphabetical List

inportl
=======

Syntax
------

     #include <pc.h>

     unsigned long inportl(unsigned short _port);

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.

Return Value
------------

The value returned from the port.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: inportsb,  Next: inportsl,  Prev: inportl,  Up: Alphabetical List

inportsb
========

Syntax
------

     #include <pc.h>

     void inportsb(unsigned short _port, unsigned char *_buf, unsigned _len);

Description
-----------

Reads the 8-bit _PORT _LEN times, and stores the bytes in BUF.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: inportsl,  Next: inportsw,  Prev: inportsb,  Up: Alphabetical List

inportsl
========

Syntax
------

     #include <pc.h>

     void inportsl(unsigned short _port, unsigned long *_buf, unsigned _len);

Description
-----------

Reads the 32-bit _PORT _LEN times, and stores the bytes in BUF.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: inportsw,  Next: inportw,  Prev: inportsl,  Up: Alphabetical List

inportsw
========

Syntax
------

     #include <pc.h>

     void inportsw(unsigned short _port,
                   unsigned short *_buf, unsigned _len);

Description
-----------

Reads the 16-bit _PORT _LEN times, and stores the bytes in BUF.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: inportw,  Next: inpw,  Prev: inportsw,  Up: Alphabetical List

inportw
=======

Syntax
------

     #include <pc.h>

     unsigned short inportw(unsigned short _port);

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.

Return Value
------------

The value returned through the port.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: inpw,  Next: insline,  Prev: inportw,  Up: Alphabetical List

inpw
====

Syntax
------

     #include <pc.h>

     unsigned short inpw(unsigned short _port);

Description
-----------

Calls *Note inportw::.  Provided only for compatibility.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: insline,  Next: insque,  Prev: inpw,  Up: Alphabetical List

insline
=======

Syntax
------

     #include <conio.h>

     void insline(void);

Description
-----------

A blank line is inserted at the current cursor position.  The previous
line and lines below it scroll down.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: insque,  Next: __install_dev_full,  Prev: insline,  Up: Alphabetical List

insque
======

Syntax
------

     #include <search.h>

     void insque(struct qelem *elem, struct qelem *pred);

Description
-----------

This function manipulates queues built from doubly linked lists.  Each
element in the queue must be in the form of `struct qelem' which is
defined thus:

     struct qelem {
       struct qelem *q_forw;
       struct qelem *q_back;
       char q_data[0];
     }

This function inserts ELEM in a queue immediately after PRED.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __install_dev_full,  Next: __install_dev_zero,  Prev: insque,  Up: Alphabetical List

__install_dev_full
==================

Syntax
------

     #include <sys/xdevices.h>

     int __install_dev_full (void);

Description
-----------

This function activates support for the special file `/dev/full'.  When
read, `dev/full' always returns `\0' characters.  Writes to `/dev/full'
will fail with `errno' set to `ENOSPC'.  Seeks on `/dev/full' always
succeed.

The DJGPP debug support functions will interfere with `/dev/full'
(*note File System Extensions::).

Return Value
------------

On success, a non-zero value is returned; on failure, zero is returned.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __install_dev_zero,  Next: int386,  Prev: __install_dev_full,  Up: Alphabetical List

__install_dev_zero
==================

Syntax
------

     #include <sys/xdevices.h>

     int __install_dev_zero (void);

Description
-----------

This function activates support for the special file `/dev/zero'.  When
read, `dev/zero' always returns `\0' characters.  When written,
`/dev/zero' discards the data.  Seeks on `/dev/zero' will always
succeed.

The DJGPP debug support functions will interfere with `/dev/zero'
(*note File System Extensions::).

Return Value
------------

On success, a non-zero value is returned; on failure, zero is returned.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: int386,  Next: int386x,  Prev: __install_dev_zero,  Up: Alphabetical List

int386
======

Syntax
------

     #include <dos.h>

     int int386(int ivec, union REGS *in, union REGS *out);

Description
-----------

This function is equal to `int86' function.  See *Note int86::, for
further description.

Return Value
------------

The returned value of `EAX'.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: int386x,  Next: int86,  Prev: int386,  Up: Alphabetical List

int386x
=======

Syntax
------

     #include <dos.h>

     int int386x(int ivec, union REGS *in, union REGS *out,
                 struct SREGS *seg);

Description
-----------

This function is equal to `int86x'.  See *Note int86::, for further
description.

Return Value
------------

The value of `EAX' is returned.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: int86,  Next: int86x,  Prev: int386x,  Up: Alphabetical List

int86
=====

Syntax
------

     #include <dos.h>

     int int86(int ivec, union REGS *in, union REGS *out);

Description
-----------

The `union REGS' is defined by `<dos.h>' as follows:

     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;
     };

Note: The `.x.' branch is a problem generator.  Most programs expect
the `.x.' branch to have e.g. "`.x.ax'" members, and that they are
16-bit.  If you know you want 32-bit values, use the `.d.eax' members.
If you know you want 16-bit values, use the `.w.ax' members.  The `.x.'
members behave according to `#defines', as follows:

`default'
     If you specify no `#define', the `.x.' branch has "`ax'" members
     and is 32-bit.  This is compatible with previous versions of djgpp.

`_NAIVE_DOS_REGS'
     This define gives you `.x.ax', but they are 16-bit.  This is
     probably what most programs ported from 16-bit dos compilers will
     want.

`_BORLAND_DOS_REGS'
     This define gives you `.x.eax' which are 32-bit.  This is
     compatible with Borland's 32-bit compilers.


This function simulates a software interrupt.  Note that, unlike the
`__dpmi_int' function, requests that go through `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 `BX', `int86' expects you to put
a (protected-mode) pointer in `EBX'.  Therefore, `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 IN.
After the interrupt, the CPU registers are copied to OUT.

This function is just like `int86x' (*note int86x::) except that
suitable default values are used for the segment registers.

See also *Note int86x::, *Note intdos::, and *Note bdos::.

Return Value
------------

The returned value of `EAX'.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     union REGS r;
     r.x.ax = 0x0100;
     r.h.dl = 'c';
     int86(0x21, &r, &r);


File: libc.info,  Node: int86x,  Next: intdos,  Prev: int86,  Up: Alphabetical List

int86x
======

Syntax
------

     #include <dos.h>

     int int86x(int ivec, union REGS *in, union REGS *out,
                struct SREGS *seg);

Description
-----------

The `struct SREGS' is defined by `<dos.h>' as follows:

     struct SREGS {
       unsigned short es;
       unsigned short ds;
       unsigned short fs;
       unsigned short gs;
       unsigned short cs;
       unsigned short ss;
     };

This function is just like `int86' (*note int86::) except that values
you pass in SEG are used for the segment registers instead of the
defaults.

See also *Note int86::, *Note intdos::, and *Note bdos::.

Return Value
------------

The value of `EAX' is returned.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: intdos,  Next: intdosx,  Prev: int86x,  Up: Alphabetical List

intdos
======

Syntax
------

     #include <dos.h>

     int intdos(union REGS *in, union REGS *out);

Description
-----------

This function is just like `int86' (*note int86x::) except that the
interrupt vector is 0x21.

Return Value
------------

`EAX'

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: intdosx,  Next: intensevideo,  Prev: intdos,  Up: Alphabetical List

intdosx
=======

Syntax
------

     #include <dos.h>

     int intdosx(union REGS *in, union REGS *out, struct SREGS *s);

Description
-----------

This function is just like `int86x' (*note int86x::) except that the
interrupt vector is 0x21.

Return Value
------------

`EAX'

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: intensevideo,  Next: __internal_readlink,  Prev: intdosx,  Up: Alphabetical List

intensevideo
============

Syntax
------

     #include <conio.h>

     void intensevideo(void);

Description
-----------

Bit 7 (`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
`blinkvideo' (*note 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 `0040h:0065h' in the BIOS area indicates
the current state: if it's 1 (the default), blinking characters will be
displayed.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __internal_readlink,  Next: _invent_inode,  Prev: intensevideo,  Up: Alphabetical List

__internal_readlink
===================

Syntax
------

     #include <libc/symlink.h>

     int __internal_readlink(const char * path, int fhandle,
                             char * buf, size_t max)

Description
-----------

In general applications shouldn't call this function; use `readlink'
instead (*note readlink::).  However, there is one exception: if you
have a `FSEXT' `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 `S_IFLNK' bit in `st_mode'.  This function
operates on either PATH *or* FHANDLE. In any case, the other arg should
be set to `NULL' or 0.

Return Value
------------

Number of copied characters; value -1 is returned in case of error and
`errno' is set.  When value returned is equal to SIZE, you cannot
determine if there was enough room to copy whole name.  So increase
SIZE and try again.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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.");


File: libc.info,  Node: _invent_inode,  Next: ioctl (DOS),  Prev: __internal_readlink,  Up: Alphabetical List

_invent_inode
=============

Syntax
------

     ino_t
     _invent_inode(const char *name, unsigned time_stamp,
                   unsigned long fsize)

Description
-----------

This invents an inode number for those files which don't have valid DOS
cluster number.  These could be:
   *  devices like `/dev/null' or file system extensions  (*note File
     System Extensions::)

   *  empty files which were not allocated disk space yet

   *  or files on networked drives, for which the redirector doesn't
     bring the  cluster number.

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
`truename()' (*note _truename::), or that returned by `_fixpath()'
(*note _fixpath::).  The point here is that the entire program _must_
abide by these conventions through its operation, or else you risk
getting different inode numbers for the same file.

Return Value
------------

0 on error, otherwise the invented inode number for the file.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: ioctl (DOS),  Next: ioctl (General description),  Prev: _invent_inode,  Up: Alphabetical List

ioctl (DOS)
===========

The DOSish version of `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
`sys/ioctl.h'.

Syntax
------

     #include <sys/ioctl.h>

     int ioctl(int fd, int cmd, ... );

Description
-----------

The parameter `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 `cmd' parameter:
`DOS_GETDEVDATA'
     Get device information. Returns the device information word from
     `DX'.  The call to `ioctl' should look like this:

           int ret_val = ioctl (fd, DOS_GETDEVDATA);

     For another way of achieving the same effect, see `_get_dev_info'
     (*note _get_dev_info::).

`DOS_SETDEVDATA'
     Set device information. Returns the new device information word
     form `DX' or -1.  The call to `ioctl' should look like this:

           int ret_val = ioctl (fd, DOS_SETDEVDATA, 0, dev_info);

`DOS_RCVDATA'
     Read from character device control channel. After `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 `ioctl' should look like this:

           unsigned char buf[bytes_to_read];
           int ret_val = ioctl (fd, DOS_RCVDATA, bytes_to_read, &buf);

`DOS_SNDDATA'
     Write to character device control channel. After `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:

           unsigned char buf[bytes_to_write];
           int ret_val = ioctl (fd, DOS_SNDDATA, bytes_to_write, &buf);

`DOS_RCVCTLDATA'
     Read from block device control channel. See `DOS_RCVDATA'.

`DOS_SNDCTLDATA'
     Write to block device control channel. See `DOS_SNDDATA'.

`DOS_CHKINSTAT'
     Check the input status of a file. Returns 0 if not ready of at
     EOF, `0xff' if file is ready.  Here's an example of how to call:

           int ret_val = ioctl (fd, DOS_CHKINSTAT);

     A more portable way of doing this is by calling `select'.  *Note
     select::.

`DOS_CHKOUTSTAT'
     Check the output status of a file. Returns 0 if not ready of at
     EOF, `0xff' if file is ready.  `select' (*note select::) is
     another, more portable way of doing the same.

`DOS_ISCHANGEABLE'
     Check if a block device is changeable. Returns 0 for removable or
     1 for fixed.  An example of a call:

           int ret_val = ioctl (fd, DOS_ISCHANGEABLE);

`DOS_ISREDIRBLK'
     Check if a block device is remote o local.  The function
     `_is_remote_drive' (*note _is_remote_drive::) is another way of
     returning the same info.

`DOS_ISREDIRHND'
     Check if a file handle refers to a local or remote device.  See
     `_is_remote_handle' (*note _is_remote_handle::) for another way of
     doing this.

`DOS_SETRETRY'
     Set the sharing retry count. The first extra parameter specifies
     the pause between retries, the second number of retries.  An
     example:

           int ret_val = ioctl (fd, DOS_SETRETRY, pause_between_retries,
                                max_retries);

`DOS_GENCHARREQ'
     Generic character device request.  Example:

           int ret_val = ioctl (fd, DOS_GENCHARREQ, category_and_function,
                                &param_block, si_value, di_value,
                                param_block_size);

     Refer to Ralf Brown's Interrupt List for the details about each
     function and relevant parameter block layout.

`DOS_GENBLKREQ'
     Generic block device request.  Example of the call:

           int ret_val = ioctl (drive_no, DOS_GENBLKREQ, category_and_function,
                                &param_block, si_value, di_value,
                                param_block_size);

     Note that instead of the handle, the first argument is the disk
     drive number (0 = default, 1 = A:, etc.).

`DOS_GLDRVMAP'
     Get logical drive map.  A call like the following:

           int ret_val = ioctl (drive_no, DOS_GLDRVMAP);

     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 `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".

`DOS_SLDRVMAP'
     Set logical drive map.  For example, a call like this:

           ioctl (1, DOS_SLDRVMAP);

     will cause drive A: to be mapped to drive B:.

`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:

           int ret_val = ioctl (fd, DOS_QGIOCTLCAPH, category_and_function);

     This will return zero if the specified IOCTL function is
     supported, 1 if not.

`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.

If your specific device driver requires different commands, they must
be or'ed together with the flags listed in `<sys/ioctl.h>' to tell the
drive about transfer buffers and what to return.

Return Value
------------

See description above.

Device information word
-----------------------

The bits of the device information word have the following meaning:

Character device:
14
     Device driver can process IOCTL request

13
     output until busy supported

11
     driver supports OPEN/CLOSE calls

7
     set (indicates device)

6
     EOF on input

5
     raw (binary) mode

4
     device is special (uses INT 29)

3
     clock device

2
     NUL device

1
     standard output

0
     standard input


Disk file:
15
     file is remote (DOS 3.0+)

14
     don't set file date/time on closing (DOS 3.0+)

11
     media not removable

8
     (DOS 4 only) generate INT 24 if no disk space on write or read
     past end of file

7
     clear (indicates file)

6
     file has not been written

5-0
     drive number (0 = A:)


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);
     }


File: libc.info,  Node: ioctl (General description),  Next: ioctl (UNIX),  Prev: ioctl (DOS),  Up: Alphabetical List

ioctl (General description)
===========================

`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 `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.


File: libc.info,  Node: ioctl (UNIX),  Next: _is_cdrom_drive,  Prev: ioctl (General description),  Up: Alphabetical List

ioctl (UNIX)
============

Syntax
------

     #include <sys/ioctl.h>

     int ioctl(int fd, int cmd, ... );

Description
-----------

The UNIX version first checks if an FSEXT handler is associated with
the file descriptor FD. If so, it calls the handler in the usual way
(*note File System Extensions::).

Otherwise,the operation specified by CMD is performed on the file open
on handle FD.  The following operations are defined by the header
`sys/ioctl.h':

`TIOCGWINSZ'
     Fill in the `winsize' structure pointed to by the third argument
     with the screen width and height.

     The `winsize' structure is defined in `sys/ioctl.h' as follows:

          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 */
          };


Return Value
------------

Zero for `TIOCGWINSZ'. Otherwise, -1 is returned and `errno' is set to
`ENOSYS' for all others.

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;
     }


File: libc.info,  Node: _is_cdrom_drive,  Next: _is_DOS83,  Prev: ioctl (UNIX),  Up: Alphabetical List

_is_cdrom_drive
===============

Syntax
------

     #include <dos.h>

     int _is_cdrom_drive( const int drive );

Description
-----------

This function checks if drive number DRIVE (1 == A:, 2 == B:, etc.) is
a CD-ROM drive.  It works with MSCDEX 2.x and Windows 9X built-in CDFS
support.

Return Value
------------

1 if the drive is a CDROM drive, otherwise 0.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);
     }


File: libc.info,  Node: _is_DOS83,  Next: _is_executable,  Prev: _is_cdrom_drive,  Up: Alphabetical List

_is_DOS83
=========

Syntax
------

     #include <fcntl.h>

     int _is_DOS83 (const char *fname);

Description
-----------

This function checks the filename pointed to by 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 `+' `,' `;' `=' `[' `]', or a space.  The
special names `.' and `..' 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 *note _preserve_fncase:: is false.

Return value
------------

The function returns an integer 0 (not DOS 8.3) or 1 (DOS 8.3)

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _is_executable,  Next: _is_fat32,  Prev: _is_DOS83,  Up: Alphabetical List

_is_executable
==============

Syntax
------

     #include <sys/stat.h>

     int _is_executable(const char *path, int fhandle,
                        const char *extension);

Description
-----------

This function determines if a file is executable under DOS/DJGPP
environment.  The file may be given either by its PATH or its file
handle FHANDLE.  If 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 `_STAT_EXEC_EXT' bit of the
`_djstat_flags' global variable (*note _djstat_flags::) is not set,
this step is skipped.)  If 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 `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 `_STAT_EXEC_MAGIC' bit of the `_djstat_flags'
variable is set.)

Note that if `_STAT_EXEC_MAGIC' is set, but `_STAT_EXEC_EXT' is not,
some files which shouldn't be flagged as executables (e.g., COFF `*.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 `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
`magic number'.

This function is used internally by `f?stat'; you are not supposed to
call it directly.  However, if you call it, and pass file through PATH,
it's up to you to resolve symlinks there.

Return Value
------------

1 for executable file, 0 otherwise (including in case of errors in
accessing the file).

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _is_fat32,  Next: _is_ram_drive,  Prev: _is_executable,  Up: Alphabetical List

_is_fat32
=========

Syntax
------

     #include <dos.h>

     int _is_fat32( const int drive );

Description
-----------

This function checks if drive number 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.

Return Value
------------

1 if the drive is formatted with FAT32, otherwise 0.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);
     }


File: libc.info,  Node: _is_ram_drive,  Next: _is_remote_drive,  Prev: _is_fat32,  Up: Alphabetical List

_is_ram_drive
=============

Syntax
------

     #include <dos.h>

     int _is_ram_drive( const int drive );

Description
-----------

This function checks if drive number 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 _have_ to be so, but if it's good enough for Andrew Schulman et
al (`Undocumented DOS, 2nd edition'), we can use this as well.

Return Value
------------

1 if the drive is a RAM drive, otherwise 0.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 ) )


File: libc.info,  Node: _is_remote_drive,  Next: _is_remote_handle,  Prev: _is_ram_drive,  Up: Alphabetical List

_is_remote_drive
================

Syntax
------

     int _is_remote_drive(int drv);

Description
-----------

Given the drive number in 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.

Return Value
------------

Zero for local drives, non-zero for remote and CD-ROM drives.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _is_remote_handle,  Next: isalnum,  Prev: _is_remote_drive,  Up: Alphabetical List

_is_remote_handle
=================

Syntax
------

     int _is_remote_handle(int fhandle);

Description
-----------

Given the file handle of an open file in 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.

Return Value
------------

Zero for files on local drives, non-zero for files on remote and CD-ROM
drives.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: isalnum,  Next: isalpha,  Prev: _is_remote_handle,  Up: Alphabetical List

isalnum
=======

Syntax
------

     #include <ctype.h>

     int isalnum(int c);

Description
-----------

Tells if C is any letter or digit.

Return Value
------------

Nonzero if C is a letter or digit, else zero.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: isalpha,  Next: isascii,  Prev: isalnum,  Up: Alphabetical List

isalpha
=======

Syntax
------

     #include <ctype.h>

     int isalpha(int c);

Description
-----------

Tells if C is a letter.

Return Value
------------

Nonzero if C is a letter, else zero.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: isascii,  Next: isatty,  Prev: isalpha,  Up: Alphabetical List

isascii
=======

Syntax
------

     #include <ctype.h>

     int isascii(int c);

Description
-----------

Tells if C is an ASCII character (0x00 to 0x7f).

Return Value
------------

Nonzero if C is ASCII, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: isatty,  Next: isblank,  Prev: isascii,  Up: Alphabetical List

isatty
======

Syntax
------

     #include <unistd.h>

     int isatty(int fd);

Description
-----------

Tells if the file descriptor refers to a terminal device or not.

Return Value
------------

Nonzero if FD is a terminal device, zero  otherwise.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     if (isatty(1))
       fflush(stdout);


File: libc.info,  Node: isblank,  Next: iscntrl,  Prev: isatty,  Up: Alphabetical List

isblank
=======

Syntax
------

     #include <ctype.h>

     int isblank(int c);

Description
-----------

Tells if C is a blank character.  A blank character is used to separate
words, e.g.: ` ' or `\t'.

Return Value
------------

Nonzero if C is a blank character, else zero.

Portability
-----------

ANSI/ISO C   C99; not C89
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: iscntrl,  Next: isdigit,  Prev: isblank,  Up: Alphabetical List

iscntrl
=======

Syntax
------

     #include <ctype.h>

     int iscntrl(int c);

Description
-----------

Tells if C is a control character.

Return Value
------------

Nonzero if C is a control character, else zero.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: isdigit,  Next: isfinite,  Prev: iscntrl,  Up: Alphabetical List

isdigit
=======

Syntax
------

     #include <ctype.h>

     int isdigit(int c);

Description
-----------

Tells if C is a digit.

Return Value
------------

Nonzero if C is a digit, else zero.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: isfinite,  Next: isgraph,  Prev: isdigit,  Up: Alphabetical List

isfinite
========

Syntax
------

     #include <math.h>

     int isfinite(x);

Description
-----------

The macro `isfinite' will determine whether its argument X has a finite
value (zero, subnormal, or normal, and not infinite or NaN).  The
operands can be of any real floating-point type.

Return Value
------------

non-zero for a finite value; zero else.

Portability
-----------

ANSI/ISO C   C99; not C89

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");


File: libc.info,  Node: isgraph,  Next: isgreater,  Prev: isfinite,  Up: Alphabetical List

isgraph
=======

Syntax
------

     #include <ctype.h>

     int isgraph(int c);

Description
-----------

Tells if C is a visible printing character.  Space is not included.

Return Value
------------

Nonzero if C is a visible printing character, else zero.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: isgreater,  Next: isgreaterequal,  Prev: isgraph,  Up: Alphabetical List

isgreater
=========

Syntax
------

     #include <math.h>

     int isgreater(x, y);

Description
-----------

The macro `isgreater' will determine whether its first argument X is
greater than its second argument Y without failing if one of the
operands is `NaN'.  The operands can be of any real floating-point type
and the macro is guaranteed to evaluate their operands only once.

Return Value
------------

zero if one of X or Y is `NaN'; else the result of (X) > (Y).

Portability
-----------

ANSI/ISO C   C99; not C89

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");
     }


File: libc.info,  Node: isgreaterequal,  Next: isinf,  Prev: isgreater,  Up: Alphabetical List

isgreaterequal
==============

Syntax
------

     #include <math.h>

     int isgreaterequal(x, y);

Description
-----------

The macro `isgreaterequal' will determine whether its first argument X
is greater than or equal to its second argument Y without failing if
one of the operands is `NaN'.  The operands can be of any real
floating-point type and the macro is guaranteed to evaluate their
operands only once.

Return Value
------------

zero if one of X or Y is `NaN'; else the result of (X) >= (Y).

Portability
-----------

ANSI/ISO C   C99; not C89

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");
     }


File: libc.info,  Node: isinf,  Next: isless,  Prev: isgreaterequal,  Up: Alphabetical List

isinf
=====

Syntax
------

     #include <math.h>

     int isinf(x);

Description
-----------

The macro `isinf' will determine whether its argument X value is a
positive or negative infinity.  The operands can be of any real
floating-point type.

Return Value
------------

non-zero for a infinite value (positive or negative); zero else.

Portability
-----------

ANSI/ISO C   C99; not C89

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");


File: libc.info,  Node: isless,  Next: islessequal,  Prev: isinf,  Up: Alphabetical List

isless
======

Syntax
------

     #include <math.h>

     int isless(x, y);

Description
-----------

The macro `isless' will determine whether its first argument X is less
than its second argument Y without failing if one of the operands is
`NaN'.  The operands can be of any real floating-point type and the
macro is guaranteed to evaluate their operands only once.

Return Value
------------

zero if one of X or Y is `NaN'; else the result of (X) < (Y).

Portability
-----------

ANSI/ISO C   C99; not C89

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");
     }


File: libc.info,  Node: islessequal,  Next: islessgreater,  Prev: isless,  Up: Alphabetical List

islessequal
===========

Syntax
------

     #include <math.h>

     int islessequal(x, y);

Description
-----------

The macro `islessequal' will determine whether its first argument X is
less than or equal to its second argument Y without failing if one of
the operands is `NaN'.  The operands can be of any real floating-point
type and the macro is guaranteed to evaluate their operands only once.

Return Value
------------

zero if one of X or Y is `NaN'; else the result of (X) <= (Y).

Portability
-----------

ANSI/ISO C   C99; not C89

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");
     }


File: libc.info,  Node: islessgreater,  Next: islower,  Prev: islessequal,  Up: Alphabetical List

islessgreater
=============

Syntax
------

     #include <math.h>

     int islessgreater(x, y);

Description
-----------

The macro `islessgreater' will determine whether its first argument X
is less than or greater than its second argument Y without failing if
one of the operands is `NaN'.  The operands can be of any real
floating-point type and the macro is guaranteed to evaluate their
operands only once.

Return Value
------------

zero if one of X or Y is `NaN'; else the result of (X) < (Y) || (X) >
(Y).

Portability
-----------

ANSI/ISO C   C99; not C89

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");
     }


File: libc.info,  Node: islower,  Next: isnan,  Prev: islessgreater,  Up: Alphabetical List

islower
=======

Syntax
------

     #include <ctype.h>

     int islower(int c);

Description
-----------

Tells if C is lower case or not.

Return Value
------------

Nonzero if C is lower case, else zero.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: isnan,  Next: isnormal,  Prev: islower,  Up: Alphabetical List

isnan
=====

Syntax
------

     #include <math.h>

     int isnan(x);

Description
-----------

The macro `isnan' will determine whether its argument X is a NaN.  The
operands can be of any real floating-point type.

Return Value
------------

non-zero for NaN; zero else.

Portability
-----------

ANSI/ISO C   C99; not C89

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");


File: libc.info,  Node: isnormal,  Next: isprint,  Prev: isnan,  Up: Alphabetical List

isnormal
========

Syntax
------

     #include <math.h>

     int isnormal(x);

Description
-----------

The macro `isnormal' will determine whether its argument X is normal
(neither zero, subnormal, infinite nor NaN).  The operands can be of
any real floating-point type.

Return Value
------------

non-zero for a normal value; zero else.

Portability
-----------

ANSI/ISO C   C99; not C89

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");


File: libc.info,  Node: isprint,  Next: ispunct,  Prev: isnormal,  Up: Alphabetical List

isprint
=======

Syntax
------

     #include <ctype.h>

     int isprint(int c);

Description
-----------

Tells if C is a printing character, which includes the space character.

Return Value
------------

Nonzero if C is a printing character, else zero.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: ispunct,  Next: isspace,  Prev: isprint,  Up: Alphabetical List

ispunct
=======

Syntax
------

     #include <ctype.h>

     int ispunct(int c);

Description
-----------

Tells if C is any printing character except space and those indicated
by `isalnum'.

Return Value
------------

Nonzero if C is punctuation, else zero.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: isspace,  Next: isunordered,  Prev: ispunct,  Up: Alphabetical List

isspace
=======

Syntax
------

     #include <ctype.h>

     int isspace(int c);

Description
-----------

Tells if C is whitespace, that is, carriage return, newline, form feed,
tab, vertical tab, or space.

Return Value
------------

Nonzero if C is whitespace, else zero.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: isunordered,  Next: isupper,  Prev: isspace,  Up: Alphabetical List

isunordered
===========

Syntax
------

     #include <math.h>

     int isunordered(x);

Description
-----------

The macro `isunordered' will determine whether its arguments X or Y are
unordered.  The operands can be of any real floating-point type.

Return Value
------------

non-zero if one of X or Y is `NaN'; zero else.

Portability
-----------

ANSI/ISO C   C99; not C89

Example
-------

     float pi = 3.14159;
     long double x = NAN;

     if (isunordered(pi, x))
       printf("one of the values is NaN.\n");


File: libc.info,  Node: isupper,  Next: isxdigit,  Prev: isunordered,  Up: Alphabetical List

isupper
=======

Syntax
------

     #include <ctype.h>

     int isupper(int c);

Description
-----------

Tells if C is an upper case character or not.

Return Value
------------

Nonzero if C is upper case, else zero.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: isxdigit,  Next: itoa,  Prev: isupper,  Up: Alphabetical List

isxdigit
========

Syntax
------

     #include <ctype.h>

     int isxdigit(int c);

Description
-----------

Tells if C is a valid hexadecimal digit or not.  This includes
`[0-9a-fA-F]'.

Return Value
------------

Nonzero if C is a hex digit, else zero.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: itoa,  Next: kbhit,  Prev: isxdigit,  Up: Alphabetical List

itoa
====

Syntax
------

     #include <stdlib.h>

     char * itoa(int value, char *string, int radix)

Description
-----------

This function converts its argument VALUE into a null-terminated
character string using 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 `NULL' is put into the buffer whose address is
given by STRING.  For radixes other than 10, VALUE is treated as an
unsigned int (i.e., the sign bit is not interpreted as such).  The
argument RADIX should specify the base, between 2 and 36, in which the
string representation of VALUE is requested.

Return Value
------------

A pointer to STRING.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     char binary_str[33];

     (void)itoa(num, binary_str, 2);


File: libc.info,  Node: kbhit,  Next: kill,  Prev: itoa,  Up: Alphabetical List

kbhit
=====

Syntax
------

     #include <pc.h>

     int kbhit(void);

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 `bioskey
(2)' or `bioskey (0x12)') then you should also use bios calls for
testing for keys.  This can be done with by `bioskey (1)' or `bioskey
(0x11)'.  Failing to do so can cause trouble in multitasking
environments like DESQview/X.

Return Value
------------

Nonzero if a key has been hit, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     while (!kbhit())
       do_stuff();


File: libc.info,  Node: kill,  Next: l64a,  Prev: kbhit,  Up: Alphabetical List

kill
====

Syntax
------

     #include <signal.h>

     int	kill(pid_t _pid, int _sig);

Description
-----------

If _PID is the current `getpid()', the given _SIG is raised with *Note
raise::.

Return Value
------------

-1 on error, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: l64a,  Next: labs,  Prev: kill,  Up: Alphabetical List

l64a
====

Syntax
------

     #include <stdlib.h>

     char *l64a(long value);

Description
-----------

This function takes a `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 `long' value by the `a64l'
function (*note a64l::).

Return Value
------------

A pointer to a static buffer containing the radix-64 representation of
VALUE.  Subsequent calls will overwrite the contents of this buffer.
If VALUE is `0L', this function returns an empty string.

Radix-64
--------

The radix-64 ASCII representation is a notation whereby 32-bit integers
are represented by up to 6 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 `long'
type is more than 32 bits in size, only the low-order 32 bits are used.
The characters used to represent digits are `.' (dot) for 0, `/' for 1,
`0' through `9' for 2 to 11, `A' through `Z' for 12 to 37, and `a'
through `z' for 38 to 63.

Note that this is _not_ the same encoding used by either uuencode or the
MIME base64 encoding.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)

Notes:

  1. This function is new to the Posix 1003.1-200x draft


File: libc.info,  Node: labs,  Next: lchown,  Prev: l64a,  Up: Alphabetical List

labs
====

Syntax
------

     #include <stdlib.h>

     long labs(long x);

Description
-----------

This function takes the absolute value of X.  *Note abs::.

Return Value
------------

|X|

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: lchown,  Next: ldexp,  Prev: labs,  Up: Alphabetical List

lchown
======

Syntax
------

     #include <unistd.h>

     int lchown(const char *file, int owner, int group);

Description
-----------

This function does nothing under MS-DOS.

Return Value
------------

This function always returns zero if the file exists (it does not
follow symbolic links), else it returns -1 and sets `errno' to `ENOENT'.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: ldexp,  Next: ldiv,  Prev: lchown,  Up: Alphabetical List

ldexp
=====

Syntax
------

     #include <math.h>

     double ldexp(double val, int exp);

Description
-----------

This function computes VAL*2^EXP.

Return Value
------------

VAL*2^EXP.  `ldexp(0., exp)' returns 0 for all values of `exp', without
setting `errno'.  For non-zero values of VAL, `errno' is set to
`ERANGE' if the result cannot be accurately represented by a `double',
and the return value is then the nearest representable `double'
(possibly, an `Inf').  If VAL is a `NaN' or `Inf', the return value is
`NaN' and `errno' is set to `EDOM'.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     ldexp(3.5,4) == 3.5 * (2^4) == 56.0


File: libc.info,  Node: ldiv,  Next: lfilelength,  Prev: ldexp,  Up: Alphabetical List

ldiv
====

Syntax
------

     #include <stdlib.h>

     ldiv_t ldiv(long numerator, long denominator);

Description
-----------

Returns the quotient and remainder of the division NUMERATOR divided by
DENOMINATOR.  The return type is as follows:

     typedef struct {
       long quot;
       long rem;
     } ldiv_t;

Return Value
------------

The results of the division are returned.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

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 }


File: libc.info,  Node: lfilelength,  Next: lfind,  Prev: ldiv,  Up: Alphabetical List

lfilelength
===========

Syntax
------

     #include <io.h>

     long long lfilelength(int fhandle);

Description
-----------

This function returns the size, in bytes, of a file whose handle is
specified in the argument FHANDLE.  To get the handle of a file opened
by `fopen' (*note fopen::) or `freopen' (*note freopen::), you can use
`fileno' macro (*note fileno::).

Return Value
------------

The size of the file in bytes, or (if any error occurred) -1LL and
`errno' set to a value describing the cause of the failure.

The return value is of type `long long' which allows file sizes of
2^63-1 bytes to be returned.  Note that FAT16 limits files to near 2^31
bytes and FAT32 limits files to 2^32-2 bytes.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

       printf("Size of file to which STDIN is redirected is %ld\n",
               lfilelength(0));


File: libc.info,  Node: lfind,  Next: _lfn_gen_short_fname,  Prev: lfilelength,  Up: Alphabetical List

lfind
=====

Syntax
------

     #include <search.h>

     void * lfind(const void *key, void *base, size_t *nelp, size_t width,
                  int (*compar)(const void *, const void *));

Description
-----------

This function searches the array BASE of elements of size WIDTH,
currently containing NELP elements, for the element identified by KEY
using the comparison function COMPAR.

The function COMPAR should return 0 when its inputs are equal and not 0
otherwise.

See also `lsearch' (*note lsearch::).

Return Value
------------

A pointer to the found element or `NULL' if not present.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

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;
     }


File: libc.info,  Node: _lfn_gen_short_fname,  Next: _lfn_get_ftime,  Prev: lfind,  Up: Alphabetical List

_lfn_gen_short_fname
====================

Syntax
------

     #include <fcntl.h>

     char * _lfn_gen_short_fname (const char *long_fname, char *short_fname);

Description
-----------

This function generates a short (8+3) filename alias for the long
filename pointed to by LONG_FNAME and puts it into the buffer pointed
to by 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 LONG_FNAME must contain only the name part of
a file; elements of a full pathname (like `:' or `/' are not allowed
(they will cause the function to fail).  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 (*note _use_lfn::), the function
simply converts up to 12 characters of LONG_FNAME to upper-case and
returns that.  It will do the same if 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 `strcmp' (*note strcmp::) returns a 0 when it compares
the original long filename with the short one returned by
`_lfn_gen_short_fname', then the filename is a valid DOS name.  (Note
that if LONG_FNAME is in lower case, it might not compare equal with
SHORT_FNAME because of the case difference.)

Return value
------------

The function returns a pointer to SHORT_FNAME.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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;
     }


File: libc.info,  Node: _lfn_get_ftime,  Next: __libc_termios_exist_queue,  Prev: _lfn_gen_short_fname,  Up: Alphabetical List

_lfn_get_ftime
==============

Syntax
------

     #include <fcntl.h>

     char _lfn_get_ftime (int fhandle, int flag);

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 FHANDLE parameter is the file handle as returned by one of the
functions which open or create files.  The FLAG parameter determines
which time (creation or access) is returned.  It can be set to one of
the following:

`_LFN_ATIME'
     Causes `_lfn_get_ftime' to return the time when the file was last
     accessed.  (Currently, it actually only returns the _date_ of last
     access; the time bits are all zeroed.)

`_LFN_CTIME'
     Causes `_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.

Return value
------------

The file time stamp, as a packed unsigned int value:

`Bits 0-4'
     seconds divided by 2

`Bits 5-10'
     minutes (0-59)

`Bits 11-15'
     hours (0-23)

`Bits 16-20'
     day of the month (1-31)

`Bits 21-24'
     month (1 = January)

`Bits 25-31'
     year offset from 1980 (add 1980 to get the actual year)


If the underlying system calls fail, the function will return 0 and set
`errno' to an appropriate value.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

      unsigned file_stamp = _lfn_get_ftime (handle, _LFN_CTIME);


File: libc.info,  Node: __libc_termios_exist_queue,  Next: __libc_termios_init,  Prev: _lfn_get_ftime,  Up: Alphabetical List

__libc_termios_exist_queue
==========================

Syntax
------

     #include <libc/ttyprvt.h>

     int __libc_termios_exist_queue (void);

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.

Return Value
------------

Non-zero if some characters are buffered, zero otherwise.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __libc_termios_init,  Next: libm,  Prev: __libc_termios_exist_queue,  Up: Alphabetical List

__libc_termios_init
===================

Syntax
------

     #include <libc/ttyprvt.h>

     void __libc_termios_init (void);

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.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: libm,  Next: link,  Prev: __libc_termios_init,  Up: Alphabetical List

libm
====

Syntax
------

     #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_;

Description
-----------

The alternate math library, `libm.a', originally written by "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 `libc.a'
library, in particular when elaborate argument reduction is required to
avoid precision loss.  Functions in `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 `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 `libc.a'.

In contrast, the functions in the default `libc.a' library are written
for maximum speed and exploitation of the x87 FPU features, do not call
`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 `libc.a' and in
`libm.a' is the value returned when the result overflows a `double'.
The functions from `libc.a' always return a suitably signed infinity,
`Inf', whereas for functions from `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., Inf + a = Inf)
might be inappropriate.

Refer to *Note description of the `libm.a' functions: (libm)Math, for
detailed documentation of the individual functions from `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:

   * Include the header `<libm/math.h>'.  Alternatively, you can include
     `<math.h>' as usual and compile with `-D_USE_LIBM_MATH_H' option
     to `gcc', which will cause it to use `libm/math.h' instead of the
     default `math.h'.  (The second possibility leaves the source
     ANSI-compliant.)

   * Set the global variable `_fdlib_version' to a value other than the
     default `_IEEE_'.  The possible values are listed and explained
     below.

   * At the beginning of your `main' function, set the FPU to a
     predictable state by calling `_clear87' (*note _clear87::) and
     `_fpreset' (*note _fpreset::) library functions.  (Another
     possibility is to make these calls in a function declared with
     `__attribute__((constructor))', so it will be called before
     `main'.)

   * Link your program with the `libm.a' library, e.g. by specifying
     `-lm' on the link command line.


The functions in `libm.a' can emulate different standards.  You can
select to which standard your program will comply by setting the global
variable `_fdlib_version' (or the macro `_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.

`_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 *not* set `errno'.  If the result
     overflows, an `Inf' is returned.  This version gives the fastest
     code.

`_POSIX_'
     In case of an error, this version will set `errno' to the
     appropriate value (`EDOM' or `ERANGE') and return to the caller,
     without calling the `matherr' function (*note matherr::).  If the
     result overflows, an `Inf' is returned.  This version should be
     used for maximum POSIX- and ANSI-compliance.

`_SVID_'
     This version is compliant with the "System V Interface Definition".
     This is the slowest version.  In case of an error, it calls the
     `matherr' function (*note matherr::), which can be customized to
     the specific application needs.  If `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 `errno' is set.  If `matherr' returns non-zero, there will be
     no message and `errno' will be left unaltered.  If the result
     overflows, this version returns `HUGE', a large but finite value
     defined by `libm/math.h'.

`_XOPEN_'
     Complies to the X/Open specifications.  It behaves exactly like
     `_SVID_', but it never prints an error message, even if `matherr'
     returns zero, and `Inf' us returned when a result overflows.


Portability
-----------

ANSI/ISO C   No
POSIX        No

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);
     }


File: libc.info,  Node: link,  Next: llabs,  Prev: libm,  Up: Alphabetical List

link
====

Syntax
------

     #include <unistd.h>

     int link(const char *exists, const char *new);

Description
-----------

Because of limitations of MS-DOS, this function doesn't really link two
files together.  However, it simulates a real `link' by copying the
file at EXISTS to NEW.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     link("foo.c", "foo.bak");


File: libc.info,  Node: llabs,  Next: lldiv,  Prev: link,  Up: Alphabetical List

llabs
=====

Syntax
------

     #include <stdlib.h>

     long long int llabs(long long x);

Description
-----------

This function takes the absolute value of X.  *Note abs::.

Return Value
------------

|X|

Portability
-----------

ANSI/ISO C   C99; not C89
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992


File: libc.info,  Node: lldiv,  Next: llockf,  Prev: llabs,  Up: Alphabetical List

lldiv
=====

Syntax
------

     #include <stdlib.h>

     lldiv_t lldiv(long long int numerator, long long int denominator);

Description
-----------

Returns the quotient and remainder of the division NUMERATOR divided by
DENOMINATOR.  The return type is as follows:

     typedef struct {
       long long int quot;
       long long int rem;
     } lldiv_t;

Return Value
------------

The results of the division are returned.

Portability
-----------

ANSI/ISO C   C99; not C89
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992

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 }


File: libc.info,  Node: llockf,  Next: llrint,  Prev: lldiv,  Up: Alphabetical List

llockf
======

Syntax
------

     #include <unistd.h>

     int llockf (int fildes, int function, offset_t size);

Description
-----------

The `llockf' function is a simplified interface to the locking
facilities of `fcntl' (see *Note fcntl::, for more detailed
information).

The `llockf' function performs exactly the same functions as `lockf'
(*note lockf::), with exactly the same input commands and results, but
the input SIZE parameter is of type `offset_t' instead of `off_t', and
the `fcntl' calls are made using functions `F_GETLK64', `F_SETLK64' and
`F_SETLKW64', where `lockf' uses functions `F_GETLK', `F_SETLK' and
`F_SETLKW'.

The `llockf' function is intended to permit using `fcntl' functions
with SIZE values greater than 2^31 - 1.

FILDES is an open file descriptor.

FUNCTION is a control value which specifies the action to be taken.
The permissible values for function are defined in <unistd.h> as
follows:

     #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 */

All other values of FUNCTION are reserved for future extensions and
will result in an error return if not implemented, with `errno' set to
`EINVAL'.

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 SIZE and backward for a negative SIZE
(the preceding bytes up to but not including the current offset).  If
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 `llockf' are as follows:

`F_TEST'
     This function is used to detect if the specified section is already
     locked.

`F_LOCK'
`F_TLOCK'
     `F_LOCK' and `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.  `F_LOCK' will
     cause the calling program to wait until the resource is available.
     `F_TLOCK' will cause the function to return a -1 and set `errno'
     to `EACCES' if the section is already locked.

`F_ULOCK'
     `F_ULOCK' removes locks from a section of the file. This function
     will release locked sections controlled by the program.

The `llockf' function will fail, returning -1 and setting `errno' to
the following error values if the associated condition is true:

`EBADF'
     Parameter FILDES is not a valid open file.

`EACCES'
     Parameter FUNCTION is `F_TLOCK' or `F_TEST' and the section is
     already locked.

`EINVAL'
     Parameter FUNCTION is not one of the implemented functions.  Or:
     An attempt was made to lock a directory, which is not supported.

All lock requests in this implementation are coded as exclusive locks
(i.e. all locks use the `fcntl' request `F_WRLCK').

It is therefore wise to code `llockf' by using function `F_TLOCK' with
all lock requests, and to test the return value to determine if the
lock was obtained or not.  Using `F_TLOCK' will cause the
implementation to use `F_SETLK' instead of `F_SETLKW', which will
return an error if the lock cannot be obtained.

Return Value
------------

On success, zero is returned.  On error, -1 is returned, and `errno' is
set appropriately, as described above.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: llrint,  Next: llrintf,  Prev: llockf,  Up: Alphabetical List

llrint
======

Syntax
------

     #include <math.h>

     long long int llrint(double x);

Description
-----------

The `llrint' functions round their argument to the nearest integer
value, using the current rounding direction.

Note that unlike `rint', etc., the return type of these functions
differs from that of their arguments.

The function do not set `errno'.

Return Value
------------

Which floating-point error reporting methods are available.  The
function returns the rounded integer value of X.  If X is `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.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     long long int result = llrint(3.1415926535897932384626433832795);


File: libc.info,  Node: llrintf,  Next: llrintl,  Prev: llrint,  Up: Alphabetical List

llrintf
=======

Syntax
------

     #include <math.h>

     long long int llrintf(float x);

Description
-----------

The `llrintf' functions round their argument to the nearest integer
value, using the current rounding direction.

Note that unlike `rint', etc., the return type of these functions
differs from that of their arguments.

The function do not set `errno'.

Return Value
------------

Which floating-point error reporting methods are available.  The
function returns the rounded integer value of X.  If X is `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.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     long long int result = llrintf(3.1415926535897932384626433832795);


File: libc.info,  Node: llrintl,  Next: llseek,  Prev: llrintf,  Up: Alphabetical List

llrintl
=======

Syntax
------

     #include <math.h>

     long long int llrintl(long double x);

Description
-----------

The `llrintl' functions round their argument to the nearest integer
value, using the current rounding direction.

Note that unlike `rint', etc., the return type of these functions
differs from that of their arguments.

The function do not set `errno'.

Return Value
------------

Which floating-point error reporting methods are available.  The
function returns the rounded integer value of X.  If X is `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.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     long long int result = llrintl(3.1415926535897932384626433832795);


File: libc.info,  Node: llseek,  Next: load_npx,  Prev: llrintl,  Up: Alphabetical List

llseek
======

Syntax
------

     #include <unistd.h>

     offset_t llseek(int fd, offset_t offset, int whence);

Description
-----------

This function moves the file pointer for FD according to WHENCE:

`SEEK_SET'
     The file pointer is moved to the offset specified.

`SEEK_CUR'
     The file pointer is moved relative to its current position.

`SEEK_END'
     The file pointer is moved to a position OFFSET bytes from the end
     of the file.  The offset is usually nonpositive in this case.


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).

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.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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). */


File: libc.info,  Node: load_npx,  Next: localeconv,  Prev: llseek,  Up: Alphabetical List

load_npx
========

Syntax
------

     #include <debug/dbgcom.h>

     extern NPX npx;
     void load_npx (void);

Description
-----------

This function restores the state of the x87 numeric processor from the
data saved in the external variable `npx'.  This variable is a
structure defined as follows in the header `debug/dbgcom.h':

     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;

`load_npx' should be called immediately after `run_child' (*note
run_child::) is called to begin or resume the debugged program, and
provided that a call to `save_npx' was issued before `run_child' was
called.  *Note save_npx::.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

      save_npx ();
      run_child ();
      load_npx ();


File: libc.info,  Node: localeconv,  Next: localtime,  Prev: load_npx,  Up: Alphabetical List

localeconv
==========

Syntax
------

     #include <locale.h>

     struct lconv *localeconv(void);

Description
-----------

This function returns a pointer to a static structure that contains
information about the current locale.  The structure contains these
fields:

`char *currency_symbol'
     A string that should be used when printing local currency.

`char *decimal_point'
     A string that is used to separate the integer and fractional
     portions of real numbers in `printf'.  Currently, only the first
     character is significant.

`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 `CHAR_MAX' means to group the remainder of the digits
     together.

`char *int_curr_symbol'
     A string that should be used when formatting monetary values for
     local currency when the result will be used internationally.

`char *mon_decimal_point'
     A string that separates the integer and fractional parts of
     monetary values.

`char *mon_grouping'
     Same as grouping, but for monetary values.

`char *negative_sign'
     A string that is used to represent negative monetary values.

`char *positive_sign'
     A string that is used to represent positive monetary values.

`char *thousands_sep'
     The grouping separator for non-monetary values.

`char frac_digits'
     The number of digits to the right of the decimal point for monetary
     values.

`char int_frac_digits'
     Like frac_digits, but when formatting for international use.

`char n_cs_precedes'
     If nonzero, the currency string should precede the monetary value
     if the monetary value is negative.

`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.

`char n_sign_posn'
     Determines the placement of the negative indication string if the
     monetary value is negative.

    0
          ($value), (value$)

    1
          -$value, -value$

    2
          $value-, value$-

    3
          -$value, value-$

    4
          $-value, value$-

`char p_cs_precedes'

`char p_sep_by_space'

`char p_sign_posn'
     These are the same as n_*, but for when the monetary value is
     positive.


Note that any numeric field may have a value of `CHAR_MAX', which
indicates that no information is available.

Return Value
------------

A pointer to the `struct lconv' structure.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     struct lconv *l = localeconv;
     printf("%s%d\n", l->negative_sign, value);


File: libc.info,  Node: localtime,  Next: localtime_r,  Prev: localeconv,  Up: Alphabetical List

localtime
=========

Syntax
------

     #include <time.h>

     struct tm *localtime(const time_t *tod);

Description
-----------

Converts the time represented by TOD into a structure, correcting for
the local timezone.  *Note gmtime::, for the description of `struct tm'.

The structure pointed to is static and will be overwritten with each
call to `localtime'.  The structure should be copied if it needs to be
preserved.  *Note localtime_r::, for an alternate interface that allows
the caller to provide the structure to be filled.

Return Value
------------

A pointer to a static structure which is overwritten with each call.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: localtime_r,  Next: lock,  Prev: localtime,  Up: Alphabetical List

localtime_r
===========

Syntax
------

     #include <time.h>

     struct tm *localtime_r(const time_t * restrict tod, struct tm * restrict tptr);

Description
-----------

Converts the time represented by TOD into structure TPTR, correcting
for the local timezone.

*Note gmtime::, for the description of `struct tm'.

*Note localtime::, for an alternate ISO Standard interface.

Return Value
------------

A pointer to TPTR containing the broken down calendar time.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: lock,  Next: lock64,  Prev: localtime_r,  Up: Alphabetical List

lock
====

Syntax
------

     #include <io.h>

     int lock(int fd, long offset, long length);

Description
-----------

Locks a region in file FD using MS-DOS file sharing interface.  The
region of LENGTH bytes, starting from 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.  This function is compatible with
Borland C++ function of the same name.

*Note unlock::.

Return Value
------------

Zero if successful, nonzero if not.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: lock64,  Next: lockf,  Prev: lock,  Up: Alphabetical List

lock64
======

Syntax
------

     #include <io.h>

     int lock64(int fd, long long offset, long long length);

Description
-----------

Locks a region in file FD using MS-DOS file sharing interface.  The
region of LENGTH bytes, starting from 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 OFFSET and LENGTH must be of type `long long', thus enabling
you to lock with offsets and lengths as large as ~2^63 (FAT16 limits
this to ~2^31; FAT32 limits this to 2^32-2).

*Note unlock64::.

Return Value
------------

Zero if successful, nonzero if not.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: lockf,  Next: log,  Prev: lock64,  Up: Alphabetical List

lockf
=====

Syntax
------

     #include <unistd.h>

     int lockf (int fildes, int function, off_t size);

Description
-----------

The `lockf' function is a simplified interface to the locking
facilities of `fcntl' (see *Note fcntl::, for more detailed
information).

FILDES is an open file descriptor.

FUNCTION is a control value which specifies the action to be taken.
The permissible values for function are defined in <unistd.h> as
follows:

     #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 */

All other values of FUNCTION are reserved for future extensions and
will result in an error return if not implemented, with `errno' set to
`EINVAL'.

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 SIZE and backward for a negative SIZE
(the preceding bytes up to but not including the current offset).  If
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 `lockf' are as follows:

`F_TEST'
     This function is used to detect if the specified section is already
     locked.

`F_LOCK'
`F_TLOCK'
     `F_LOCK' and `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.  `F_LOCK' will
     cause the calling program to wait until the resource is available.
     `F_TLOCK' will cause the function to return a -1 and set `errno'
     to `EACCES' if the section is already locked.

`F_ULOCK'
     `F_ULOCK' removes locks from a section of the file.  This function
     will release locked sections controlled by the program.

The `lockf' function will fail, returning -1 and setting `errno' to the
following error values if the associated condition is true:

`EBADF'
     Parameter FILDES is not a valid open file.

`EACCES'
     Parameter FUNCTION is `F_TLOCK' or `F_TEST' and the section is
     already locked.

`EINVAL'
     Parameter FUNCTION is not one of the implemented functions.  Or:
     An attempt was made to lock a directory, which is not supported.

All lock requests in this implementation are coded as exclusive locks
(i.e. all locks use the `fcntl' request `F_WRLCK').

It is therefore wise to code `lockf' by using function `F_TLOCK' with
all lock requests, and to test the return value to determine if the
lock was obtained or not.  Using `F_TLOCK' will cause the
implementation to use `F_SETLK' instead of `F_SETLKW', which will
return an error if the lock cannot be obtained.

Return Value
------------

On success, zero is returned.  On error, -1 is returned, and `errno' is
set appropriately, as described above.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: log,  Next: log10,  Prev: lockf,  Up: Alphabetical List

log
===

Syntax
------

     #include <math.h>

     double log(double x);

Description
-----------

This function computes the natural logarithm of X.

Return Value
------------

The natural logarithm of X.  If X is zero, a negative infinity is
returned and `errno' is set to `ERANGE'.  If X is negative or `+Inf' or
a `NaN', the return value is `NaN' and `errno' is set to `EDOM'.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: log10,  Next: log1p,  Prev: log,  Up: Alphabetical List

log10
=====

Syntax
------

     #include <math.h>

     double log10(double x);

Description
-----------

This function computes the base-10 logarithm of X.

Return Value
------------

The logarithm base 10 of X.  If X is zero, a negative infinity is
returned and `errno' is set to `ERANGE'.  If X is negative or `+Inf' or
a `NaN', the return value is `NaN' and `errno' is set to `EDOM'.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: log1p,  Next: log2,  Prev: log10,  Up: Alphabetical List

log1p
=====

Syntax
------

     #include <math.h>

     double log1p(double x);

Description
-----------

This function computes the natural logarithm of 1 + X.  It is more
accurate than `log(1 + X)' for small values of X.

Return Value
------------

The natural logarithm of 1 + X.  If X is -1, a negative infinity is
returned and `errno' is set to `ERANGE'.  If X is less than -1 or
`+Inf' or a `NaN', the return value is `NaN' and `errno' is set to
`EDOM'.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: log2,  Next: longjmp,  Prev: log1p,  Up: Alphabetical List

log2
====

Syntax
------

     #include <math.h>

     double log2(double x);

Description
-----------

This function computes the base-2 logarithm of X.

Return Value
------------

The base-2 logarithm of X.  If X is zero, a negative infinity is
returned and `errno' is set to `ERANGE'.  If X is negative or `+Inf' or
a `NaN', the return value is `NaN' and `errno' is set to `EDOM'.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: longjmp,  Next: lowvideo,  Prev: log2,  Up: Alphabetical List

longjmp
=======

Syntax
------

     #include <setjmp.h>

     void longjmp(jmp_buf env, int val);

Description
-----------

This function reverts back to a CPU state that was stored in ENV by
`setjmp' (*note setjmp::).  The state includes all CPU registers, so
any variable in a register when `setjmp' was called will be preserved,
and all else will be indeterminate.

The value passed as VAL will be the return value of `setjmp' when it
resumes processing there.  If VAL is zero, the return value will be one.

Return Value
------------

This function does not return.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     jmp_buf j;
     if (setjmp(j))
       return;
     do_something();
     longjmp(j, 1);


File: libc.info,  Node: lowvideo,  Next: lrint,  Prev: longjmp,  Up: Alphabetical List

lowvideo
========

Syntax
------

     #include <conio.h>

     void    lowvideo(void);

Description
-----------

Causes any new characters put on the screen to be dim.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: lrint,  Next: lrintf,  Prev: lowvideo,  Up: Alphabetical List

lrint
=====

Syntax
------

     #include <math.h>

     long int lrint(double x);

Description
-----------

The `lrint' functions round their argument to the nearest integer value,
using the current rounding direction.

Note that unlike `rint', etc., the return type of these functions
differs from that of their arguments.

The function do not set `errno'.

Return Value
------------

Which floating-point error reporting methods are available.  The
function returns the rounded integer value of X.  If X is `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.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     long int result = lrint(3.1415926535897932384626433832795);


File: libc.info,  Node: lrintf,  Next: lrintl,  Prev: lrint,  Up: Alphabetical List

lrintf
======

Syntax
------

     #include <math.h>

     long int lrintf(float x);

Description
-----------

The `lrintf' functions round their argument to the nearest integer
value, using the current rounding direction.

Note that unlike `rint', etc., the return type of these functions
differs from that of their arguments.

The function do not set `errno'.

Return Value
------------

Which floating-point error reporting methods are available.  The
function returns the rounded integer value of X.  If X is `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.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     long int result = lrintf(3.1415926535897932384626433832795);


File: libc.info,  Node: lrintl,  Next: lsearch,  Prev: lrintf,  Up: Alphabetical List

lrintl
======

Syntax
------

     #include <math.h>

     long int lrintl(long double x);

Description
-----------

The `lrintl' functions round their argument to the nearest integer
value, using the current rounding direction.

Note that unlike `rint', etc., the return type of these functions
differs from that of their arguments.

The function do not set `errno'.

Return Value
------------

Which floating-point error reporting methods are available.  The
function returns the rounded integer value of X.  If X is `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.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     long int result = lrintl(3.1415926535897932384626433832795);


File: libc.info,  Node: lsearch,  Next: lseek,  Prev: lrintl,  Up: Alphabetical List

lsearch
=======

Syntax
------

     #include <search.h>

     void * lsearch(const void *key, void *base, size_t *nelp, size_t width,
                    int (*compar)(const void *, const void *));

Description
-----------

This function searches the array BASE of elements of size WIDTH,
currently containing NELP elements, for the element identified by KEY
using the comparison function COMPAR.

If the KEY isn't found it is added to the array BASE and *NELP is
incremented.

The function 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 `lfind' (*note lfind::).

Return Value
------------

A pointer to the found or inserted element.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

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;
     }


File: libc.info,  Node: lseek,  Next: lstat,  Prev: lsearch,  Up: Alphabetical List

lseek
=====

Syntax
------

     #include <unistd.h>

     off_t lseek(int fd, off_t offset, int whence);

Description
-----------

This function moves the file pointer for handle FD according to WHENCE:

`SEEK_SET'
     The file pointer is moved to the OFFSET specified.

`SEEK_CUR'
     The file pointer is moved OFFSET bytes relative to its current
     position.

`SEEK_END'
     The file pointer is moved to a position OFFSET bytes from the end
     of the file.  The value of OFFSET is usually nonpositive in this
     case.


Return Value
------------

The new offset is returned, or -1 and `errno' set on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     lseek(fd, 12, SEEK_CUR); /* skip 12 bytes */


File: libc.info,  Node: lstat,  Next: malldbgdmpfile,  Prev: lseek,  Up: Alphabetical List

lstat
=====

Syntax
------

     #include <sys/stat.h>

     int lstat(const char *file, struct stat *sbuf);

Description
-----------

This function obtains the status of the file FILE and stores it in
SBUF.  If FILE is a symbolic link, then `lstat' returns information
about the symbolic link.  To get information about the target of a
symbolic link, use `stat' (*note stat::) instead.

SBUF has this structure:

     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:) */
     };

The `st_atime', `st_ctime' and `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(1).  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 `lstat' sets the `st_atime' member to the same value
as `st_mtime' if the time part of `st_atime' returned by the filesystem
is zero (to prevent the situation where the file appears to have been
created _after_ it was last accessed, which doesn't look good).

The `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 `st_size' as an unsigned value.

For some drives `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 `struct stat' are very expensive to compute.  If your
application is a heavy user of `lstat' and is too slow, you can disable
computation of the members your application doesn't need, as described
in *Note _djstat_flags::.

Return Value
------------

Zero on success, nonzero on failure (and `errno' set).

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     struct stat s;
     lstat("data.txt", &s);
     if (S_ISDIR(s.st_mode))
       printf("is directory\n");

Implementation Notes
--------------------

Supplying a 100% Unix-compatible `lstat' function under DOS is an
implementation nightmare.  The following notes describe some of the
obscure points specific to `lstat's behavior in DJGPP.

1. The `drive' for character devices (like `con', `/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 `st_inode' field
will be _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 `stat', `fstat' and `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 `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 `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 `_djstat_flags' (*note _djstat_flags::) controls what
hard-to-get fields of `struct stat' are needed by the application.

7. `lstat' should not be used to get an up-to-date info about a file
which is open and has been written to, because `lstat' will only return
correct data after the file is closed.  Use `fstat' (*note fstat::)
while the file is open.  Alternatively, you can call `fflush' and
`fsync' to make the OS flush all the file's data to the disk, before
calling `lstat'.

8. The number of links `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.

---------- Footnotes ----------

(1) Even when long file names _are_ supported, the three time values
returned by `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.


File: libc.info,  Node: malldbgdmpfile,  Next: malldbgdumpfile,  Prev: lstat,  Up: Alphabetical List

malldbgdmpfile
==============

Syntax
------

     #include <stdlib.h>
     #include <malldbg.h> (on non-DJGPP systems)

     FILE *malldbgdmpfile(FILE *fp);

Description
-----------

This function allows diverting the output of the malldbg package to any
suitable text file, known as the "dumpfile".  By default the package
uses `stderr'.

Return Value
------------

The previous identity of the dumpfile.

Portability
-----------

ANSI/ISO C   No
POSIX        No

This function is specific to DJGPP.

Example
-------

     FILE *oldfile = malldbgdmpfile(stdout);


File: libc.info,  Node: malldbgdumpfile,  Next: mallinfo,  Prev: malldbgdmpfile,  Up: Alphabetical List

malldbgdumpfile
===============

Syntax
------

       FILE *fNew = fopen("mallocdbg.out", "w");
       FIKE *fOld = malldbgdumpfile(fNew);

Description
-----------

Specifies the file used by memory allocation debug functions

Return Value
------------

Returns file used earlier (before call) for this purpose.  Initial
value of output file is stderr.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: mallinfo,  Next: malloc,  Prev: malldbgdumpfile,  Up: Alphabetical List

mallinfo
========

Syntax
------

     #include <stdlib.h>
     #include <malldbg.h> /* on non-DJGPP systems */

     struct mallinfo mallinfo(void);

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 `struct mallinfo' structure is defined by
`stdlib.h' as follows:

      struct mallinfo {
        int arena;
        int ordblks;
        int smblks;
        int hblks;
        int hblkhd;
        int usmblks;
        int fsmblks;
        int uordblks;
        int fordblks;
        int keepcost;
      };

whose members are:

`arena'
     The total amount of space, in bytes, handed by `sbrk' to `malloc'.
     Note that this is not the same as `sbrk(0)', since `sbrk'
     allocates memory in large chunks and then subdivides them and
     passes them to `malloc' as required.  In particular, the result of
     `sbrk(0)' might be much larger than the `arena' member of `struct
     mallinfo' when the DPMI host allocates memory in non-contiguous
     regions (happens on MS-Windows).

`ordblks'
     The number of "ordinary blocks": the total number of allocated and
     free blocks maintained by `malloc'.

`smblks'
     The number of "small blocks".  This is normally zero, unless a
     special version of `malloc' was installed.

`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.

`hblkhd'
     The size of the currently available top portion of the memory
     assigned by `sbrk'.  Sometimes known as "slop".

`usmblks'
     The space (in bytes) in "small blocks" that are in use.  This is
     always zero in the DJGPP implementation.

`fsmblks'
     The space in free "small blocks".  Normally zero in the DJGPP
     implementation.

`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
     `malloc' to maintain its hidden information in each allocated
     block.

`fordblks'
     The amount of free heap space maintained by `malloc' in its free
     list of hblks chunks.

`keepcost'
     The total overhead used by `malloc' in maintaining the currently
     allocated blocks.

Return Value
------------

The `mallinfo' structure filled with information.

Portability
-----------

ANSI/ISO C   No
POSIX        No (see note 1)

Notes:

  1. This function is available on many Unix systems.

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);


File: libc.info,  Node: malloc,  Next: malloc_debug,  Prev: mallinfo,  Up: Alphabetical List

malloc
======

Syntax
------

     #include <stdlib.h>

     void *malloc(size_t size);

Description
-----------

This function allocates a chunk of memory from the heap large enough to
hold any object that is SIZE bytes in length.  This memory must be
returned to the heap with `free' (*note free::).

Note: excessively large requests are rejected.  At present excessively
large means over `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
(`djlsr*.zip') in the file `src/libc/ansi/stdlib/fmalloc.c'.

Return Value
------------

A pointer to the allocated memory, or `NULL' if there isn't enough free
memory to satisfy the request.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     char *c = malloc(100);


File: libc.info,  Node: malloc_debug,  Next: malloc_verify,  Prev: malloc,  Up: Alphabetical List

malloc_debug
============

Syntax
------

     #include <stdlib.h>
     #include <malldbg.h> /* on non-DJGPP systems */

     int malloc_debug(int level);

Description
-----------

This function sets the level of error diagnosis and reporting during
subsequent calls to `malloc', `free', `realloc', and all functions
which call them internally.  The argument LEVEL is interpreted as
follows:

Level 0
     The memory allocation functions behave as they do if
     `malloc_debug' was never called.  Only passive checks are allowed,
     including `malloc_verify', `mallocmap', and `malldbgdumpfile' (to
     set the output file).  In particular `mallsethook' is disabled, to
     avoid accidents.  The actual functioning of the malloc system
     remains unaffected.  Any malloc hooks set by `mallsethook' are
     reset. If errors are detected by `malloc_verify', it prints
     diagnostic messages to the "dumpfile" (default standard error
     stream), with address and size of the offending block and other
     pertinent information.

Level 1
     All the passive checks of level 0 are allowed.  In addition
     `mallsethook' is enabled, thus allowing construction of custom
     debugging packages.

Level 2
     Similar to level 1, but the consistency of the entire heap is also
     verified (by calling `malloc_verify') on every call to the memory
     allocation functions.  _Warning: this may significantly slow down
     the application._  Since the malloc hooks are in use to connect to
     this system, `mallsethook' is disabled.  If there are hooks
     already in use the change to level 2 or above is rejected.

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 `malloc' or `realloc' returns `NULL' because it cannot
     satisfy a request) are reported to the dumpfile (default standard
     error).

Level 4
     Similar to level 3, but calls to `free' with a `NULL' pointer as
     an argument are also reported.

Level -1
     Does not alter the debug level, but returns the current value.

Return Value
------------

`malloc_debug' returns the previous error diagnostic level.  The
default level is 0.

Portability
-----------

ANSI/ISO C   No
POSIX        No (see note 1)

Notes:

  1. This function is available on many Unix systems.

Example
-------

      malloc_debug(2);
      ...
      malloc_verify();


File: libc.info,  Node: malloc_verify,  Next: mallocmap,  Prev: malloc_debug,  Up: Alphabetical List

malloc_verify
=============

Syntax
------

     #include <stdlib.h>
     #include <malldbg.h> /* on non-DJGPP systems */

     int malloc_verify(void);

Description
-----------

This function attempts to determine if the heap has been corrupted.  It
scans all the blocks allocated by `malloc' and handed to the
application, and also all the free blocks maintained by `malloc' and
`free' in the internal free list.  Each block is checked for
consistency of the hidden bookkeeping information recorded in it by
`malloc' and `free'.

What happens when a bad block is found depends on the current "malloc
diagnostics level": for example, the block can be reported, or the
program may be aborted.  *Note malloc_debug::, for the details.

Return Value
------------

If the program isn't aborted during the function's run (this depends on
the current diagnostics level), `malloc_verify' returns 1 if the heap
passes all tests, or zero of some of the tests failed.

Portability
-----------

ANSI/ISO C   No
POSIX        No (see note 1)

Notes:

  1. This function is available on many Unix systems.

Example
-------

      if (malloc_verify() == 0)
        printf ("Heap corruption detected!\n");


File: libc.info,  Node: mallocmap,  Next: mallsethook,  Prev: malloc_verify,  Up: Alphabetical List

mallocmap
=========

Syntax
------

     #include <stdlib.h>
     #include <malldbg.h> /* on non-DJGPP systems */

     void mallocmap(void);

Description
-----------

This function prints a map of the heap storage to the selected
`dumpfile'. *Note 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.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No (see note 1)

Notes:

  1. This function is available on many Unix systems.


File: libc.info,  Node: mallsethook,  Next: math_errhandling,  Prev: mallocmap,  Up: Alphabetical List

mallsethook
===========

Syntax
------

     #include <stdlib.h>
     #include <malldbg.h> /* on non-DJGPP systems */

     M_HOOKFN mallsethook(enum m_hook_kind which,
                          M_HOOKFN newhook);

Description
-----------

Several "hooks" are provided for building custom `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 `free' buffers which were not allocated by `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-`NULL'; by default, all of them are initialized to
a `NULL' value.

The actual hook to be set is described by the following constants,
enumerated in `stdlib.h':

`malloc_HK = 0'
     on entry to malloc

`malloc_fail_HK'
     when malloc or realloc fails

`free_HK'
     on entry to free

`free_null_HK'
     when free is called with a NULL pointer

`realloc_HK'
     on entry to realloc

`realloc_exit_HK'
     when realloc exits.

`HKCOUNT'
     The first invalid value for a hook descriptor.

and each "callback" function is described by:

        typedef void (*M_HOOKFN)(size_t sz, void *ptr);

in `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 `NULL' as appropriate.  The callback function must *NOT* call
any of `malloc', `free', or `realloc'.

`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
`_sysmalloc' call and the `_sysinfo' struct.

`malloc_HK'
     Called just before a chunk of memory is about to be returned to
     the application in response to an allocation request.  SZ is the
     size requested by the application (*not* the actual size of the
     allocated buffer, which may be larger).  PTR is a pointer to the
     block that was allocated.

`malloc_fail_HK'
     Called if `malloc' failed to find a free block large enough to
     satisfy a request, and also failed to obtain additional memory
     from `sbrk'.  SZ is the requested allocation size.

`free_HK'
     Called when a buffer is about to be freed.  PTR is a pointer to
     the block to be freed.  Its validity has not been checked.

`free_null_HK'
     Called whenever a `NULL' pointer is passed to `free'.  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 `NULL'
     pointers in `free'.

`realloc_HK'
     Called at entry to `realloc', before the actual reallocation. PTR
     is the pointer whose contents are to be reallocated.  SZ is the
     new size requested by the application.  (This hook is called _in
     addition_ to the other hooks which may be called by `malloc' if
     and when `realloc' calls them.)

`realloc_exit_HK'
     Called at exit from `realloc'.  SZ is the requested size, and PTR
     is the (possibly) revised value of the user pointer which will be
     returned by `realloc'.  This may be `NULL' if realloc was unable
     to allocate the space, in which case _ONLY_ the original value of
     PTR (as reported by `realloc_HK') remains valid.


Return Value
------------

`mallsethook' returns the previous hook pointer, (usually `NULL'). If
`mallsethook' is disabled it will also return `NULL'.

Portability
-----------

ANSI/ISO C   No
POSIX        No

These hooks and the function are specific to DJGPP.

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 */


File: libc.info,  Node: math_errhandling,  Next: matherr,  Prev: mallsethook,  Up: Alphabetical List

math_errhandling
================

Syntax
------

     #include <math.h>

Description
-----------

`math_errhandling' evaluates to an integer expression describing the
floating-point error reporting methods used by the C library.

If `math_errhandling' returns the bit `MATH_ERRNO' set, then errors are
reported using `errno' (*note errno::).

If `math_errhandling' returns the bit `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 `errno'.

Return Value
------------

Which floating-point error reporting methods are available.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     if (math_errhandling & MATH_ERRNO)
       perror("myprogram");


File: libc.info,  Node: matherr,  Next: mblen,  Prev: math_errhandling,  Up: Alphabetical List

matherr
=======

Syntax
------

     #include <libm/math.h>

     enum fdversion _fdlib_version = _SVID_;

     int matherr(struct exception *exc);

Description
-----------

`matherr' is a user-definable handler for errors in math library
functions.  It is only supported in the alternate math library (link
with `-lm'), and will only be called if the global variable
`_fdlib_version' is set to either `_SVID_' or `_XOPEN_' (*note libm::).
You also need to mask the Invalid Operation exception in the x87
control word (*note _control87::) or install a handler for signal
`SIGFPE' (*note signal::), or else some exceptions will generate
`SIGFPE' and your program will be terminated before it gets a chance to
call `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
`matherr' when a numerical exception is detected.  The default version
of `matherr', supplied with `libm.a', does nothing and returns zero
(the `_SVID_' version will then print an error message to the standard
error stream and set `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 `matherr' in your
program.

`matherr' is called with a single argument EXC which is a pointer to a
structure defined on `<libm/math.h>' like this:

     struct exception {
     	int type;
     	char *name;
     	double arg1, arg2, retval;
     };

The member `type' is an integer code describing the type of exception
that has occurred.  It can be one of the following:

`DOMAIN'
     Argument(s) are outside the valid function domain (e.g.,
     `log(-1)').

`SING'
     Argument(s) would result in a singularity (e.g., `log(0)').

`OVERFLOW'
     The result causes overflow, like in `exp(10000)'.

`UNDERFLOW'
     The result causes underflow, like in `exp(-10000)'.

`TLOSS'
     The result loses all significant digits, like in `sin(10e100)'.

These codes are defined on `<libm/math.h>'.

The member `name' points to the string that is the name of the function
which generated the exception.  The members `arg1' and `arg2' are the
values of the arguments with which the function was called (`arg2' is
undefined if the function only accepts a single argument).  The member
`retval' is set to the default value that will be returned by the math
library function; `matherr' can change it to return a different value.

Return Value
------------

`matherr' should return zero if it couldn't handle the exception, or
non-zero if the exception was handled.

If `matherr' returns zero, under `_SVID_' version an error message is
printed which includes the name of the function and the exception type,
and under `_SVID_' and `_XOPEN_' `errno' is set to an appropriate
value.  If `matherr' returns non-zero, no error message is printed and
`errno' is left unchanged.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 */
       }


File: libc.info,  Node: mblen,  Next: mbstowcs,  Prev: matherr,  Up: Alphabetical List

mblen
=====

Syntax
------

     #include <stdlib.h>

     int mblen(const char *s, size_t n);

Description
-----------

This function returns the number of characters of string S that make up
the next multibyte character.  No more than N characters are checked.

If S is `NULL', the internal shift state is reset.

Return Value
------------

The number of characters that comprise the next multibyte character.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     int n = mblen(string, INT_MAX);
     string += n;


File: libc.info,  Node: mbstowcs,  Next: mbtowc,  Prev: mblen,  Up: Alphabetical List

mbstowcs
========

Syntax
------

     #include <stdlib.h>

     size_t mbstowcs(wchar_t *wcs, const char *s, size_t n);

Description
-----------

Converts a multibyte string to a wide character string.  The result
will be no more than N wide characters.

Return Value
------------

The number of wide characters stored.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     int wlen = mbtowcs(wbuf, string, sizeof(wbuf)/sizeof(wchar_t));


File: libc.info,  Node: mbtowc,  Next: _media_type,  Prev: mbstowcs,  Up: Alphabetical List

mbtowc
======

Syntax
------

     #include <stdlib.h>

     int mbtowc(wchar_t *pwc, const char *s, size_t n);

Description
-----------

Convert the first multibyte sequence in S to a wide character.  At most
N characters are checked.  If PWC is not `NULL', the result is stored
there.  If S is null, the internal shift state is reset.

Return Value
------------

The number of characters used by the multibyte sequence.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     string += mbtowc(&wc, string, strlen(string));


File: libc.info,  Node: _media_type,  Next: memalign,  Prev: mbtowc,  Up: Alphabetical List

_media_type
===========

Syntax
------

     #include <dos.h>

     int _media_type( const int drive );

Description
-----------

This function checks if drive number DRIVE (1 == A:, 2 == B:, etc., 0
== default drive) is fixed or removable.

`_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.

Return Value
------------

1 if the drive is a fixed disk, 0 if it is removable. -1 on error.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);
     }


File: libc.info,  Node: memalign,  Next: memccpy,  Prev: _media_type,  Up: Alphabetical List

memalign
========

Syntax
------

     #include <malloc.h>

     void *memalign(size_t alignment, size_t size);

Description
-----------

This function is like `malloc' (*note malloc::) except the returned
pointer is a multiple of ALIGNMENT. ALIGNMENT must be a power of 2.

Return Value
------------

A pointer to a newly allocated block of memory.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     char *page = memalign(1024 * 4, 1024);


File: libc.info,  Node: memccpy,  Next: memchr,  Prev: memalign,  Up: Alphabetical List

memccpy
=======

Syntax
------

     #include <string.h>

     void * memccpy(void *to, const void *from, int ch, size_t nbytes)

Description
-----------

This function copies characters from memory area FROM into TO, stopping
after the first occurrence of character CH has been copied, or after
NBYTES characters have been copied, whichever comes first.  The buffers
should not overlap.

Return Value
------------

A pointer to the character after the copy of CH in TO, or a `NULL'
pointer if CH was not found in the first NBYTES characters of FROM.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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");


File: libc.info,  Node: memchr,  Next: memcmp,  Prev: memccpy,  Up: Alphabetical List

memchr
======

Syntax
------

     #include <string.h>

     void *memchr(const void *string, int ch, size_t num);

Description
-----------

This function searches NUM bytes starting at STRING, looking for the
first occurrence of CH.

Return Value
------------

A pointer to the first match, or `NULL' if it wasn't found.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     if (memchr(path, '/', strlen(path))
       do_slash();


File: libc.info,  Node: memcmp,  Next: memcpy,  Prev: memchr,  Up: Alphabetical List

memcmp
======

Syntax
------

     #include <string.h>

     int memcmp(const void *s1, const void *s2, size_t num);

Description
-----------

This function compares two regions of memory, at S1 and S2, for NUM
bytes.

Return Value
------------

zero
     s1 == s2

positive
     s1 > s2

negative
     s1 < s2


Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: memcpy,  Next: memicmp,  Prev: memcmp,  Up: Alphabetical List

memcpy
======

Syntax
------

     #include <string.h>

     void *memcpy(void *dest, const void *src, int num);

Description
-----------

This function copies NUM bytes from SOURCE to DEST.  It assumes that
the source and destination regions don't overlap; if you need to copy
overlapping regions, use `memmove' instead.  *Note memmove::.

Return Value
------------

DEST

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     memcpy(buffer, temp_buffer, BUF_MAX);


File: libc.info,  Node: memicmp,  Next: memmove,  Prev: memcpy,  Up: Alphabetical List

memicmp
=======

Syntax
------

     #include <string.h>

     int memicmp(const void *s1, const void *s2, size_t num);

Description
-----------

This function compares two regions of memory, at S1 and S2, for NUM
bytes, disregarding case.

Return Value
------------

Zero if they're the same, nonzero if different, the sign indicates
"order".

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     if (memicmp(arg, "-i", 2) == 0)   /* '-I' or '-include' etc. */
       do_include();


File: libc.info,  Node: memmove,  Next: memset,  Prev: memicmp,  Up: Alphabetical List

memmove
=======

Syntax
------

     #include <string.h>

     void *memmove(void *dest, const void *source, int num);

Description
-----------

This function copies NUM bytes from SOURCE to 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.

Return Value
------------

DEST

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     memmove(buf+1, buf, 99);
     memmove(buf, buf+1, 99);


File: libc.info,  Node: memset,  Next: mkdir,  Prev: memmove,  Up: Alphabetical List

memset
======

Syntax
------

     #include <string.h>

     void *memset(void *buffer, int ch, size_t num);

Description
-----------

This function stores NUM copies of CH, starting at BUFFER.  This is
often used to initialize objects to a known value, like zero.

Note that, although CH is declared `int' in the prototype, `memset'
only uses its least-significant byte to fill BUFFER.

Return Value
------------

BUFFER

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     struct tm t;
     memset(&t, 0, sizeof(t));


File: libc.info,  Node: mkdir,  Next: mkdtemp,  Prev: memset,  Up: Alphabetical List

mkdir
=====

Syntax
------

     #include <sys/stat.h>

     int mkdir(const char *path, mode_t mode);

Description
-----------

This function creates a subdirectory.

All the bits except `S_IWUSR' in the MODE argument are ignored under
MS-DOS.  If `S_IWUSR' is _not_ set in 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.

Return Value
------------

Zero if the subdirectory was created, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     mkdir("/usr/tmp", S_IWUSR);


File: libc.info,  Node: mkdtemp,  Next: mkfifo,  Prev: mkdir,  Up: Alphabetical List

mkdtemp
=======

Syntax
------

     #include <stdlib.h>

     char *mkdtemp(char *template);

Description
-----------

The `mkdtemp' function generates an uniquely named temporary directory
from template.  TEMPLATE is a file specification that ends with six
trailing `X' characters.  This function replaces the `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 LFN support are
limited to eight characters for the file name, and since none of the
`X''s get replaced by a dot, you can only have two additional
characters before the `X''s.  But if the file systems offers LFN
support no limitation concerning the number of characters before the
`X''s is given and the created file names will be POSIX compliant.

Note also that the path you give will be modified in place.

Return Value
------------

The pointer to the modified template string on success, and `NULL' on
failure, in which case `errno' is set appropriately.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     char temp_dir, path[100];
     strcpy(path, _USE_LFN ? "/tmp/temp_directoryXXXXXX" : "/tmp/tdXXXXXX");
     temp_dir = mkdtemp(path);


File: libc.info,  Node: mkfifo,  Next: mknod,  Prev: mkdtemp,  Up: Alphabetical List

mkfifo
======

Syntax
------

     #include <sys/stat.h>

     int mkfifo(const char *path, mode_t mode);

Description
-----------

This function is provided only to assist in porting from Unix.  It
always returns an error condition.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: mknod,  Next: mkstemp,  Prev: mkfifo,  Up: Alphabetical List

mknod
=====

Syntax
------

     #include <sys/stat.h>

     int mknod(const char *path, mode_t mode, dev_t dev);

Description
-----------

This function is provided to assist in porting from Unix.  If MODE
specifies a regular file, `mknod' creates a file using PATH as its
name.  If MODE specifies a character device, and if the device whose
name is given by PATH exists and its device specification as returned
by `stat' or `fstat' is equal to DEV, `mknod' returns -1 and sets
`errno' to `EEXIST'.  In all other cases, -1 is returned `errno' is set
to `EACCES'.

The argument DEV is ignored if MODE does not specify a character device.

Return Value
------------

Zero on success, -1 on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: mkstemp,  Next: mktemp,  Prev: mknod,  Up: Alphabetical List

mkstemp
=======

Syntax
------

     #include <stdlib.h>

     int mkstemp(char *template);

Description
-----------

TEMPLATE is a file specification that ends with six trailing `X'
characters.  This function replaces the `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 LFN support are
limited to eight characters for the file name, and since none of the
`X''s get replaced by a dot, you can only have two additional
characters before the `X''s.  But if the file systems offers LFN
support no limitation concerning the number of characters before the
`X''s is given and the created file names will be POSIX compliant.

Note also that the path you give will be modified in place.

Return Value
------------

The open file descriptor.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)

Notes:

  1. To follow the Single Unix Specification, djgpp 2.04 has now the
     prototype in `<stdlib.h>'.  To keep backward compatibility, the
     prototype is also kept in `<stdio.h>' but its usage is deprecated.


Example
-------

     char path[100];
     strcpy(path, _USE_LFN ? "/tmp/c_compilerXXXXXX" : "/tmp/ccXXXXXX");
     int fd = mkstemp(path);


File: libc.info,  Node: mktemp,  Next: mktime,  Prev: mkstemp,  Up: Alphabetical List

mktemp
======

Syntax
------

     #include <stdlib.h>

     char *mktemp(char *template);

Description
-----------

TEMPLATE is a file specification that ends with six trailing `X'
characters.  This function replaces the `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 LFN support are
limited to eight characters for the file name, and since none of the
`X''s get replaced by a dot, you can only have two additional
characters before the `X''s.  But if the file systems offers LFN
support no limitation concerning the number of characters before the
`X''s is given and the created file names will be POSIX compliant.

Return Value
------------

If a unique name cannot be chosen, `NULL' is returned.  Otherwise the
resulting filename is returned.

Portability
-----------

ANSI/ISO C   No
POSIX        No (see note 1)

Notes:

  1. To follow the Single Unix Specification, djgpp 2.04 has now the
     prototype in `<stdlib.h>'.  To keep backward compatibility, the
     prototype is also kept in `<stdio.h>' but its usage is deprecated.


Example
-------

     char template[] = _USE_LFN ? "/tmp/c_compilerXXXXXX" : "/tmp/ccXXXXXX";
     if (mktemp(template) != NULL)
       {
         FILE *q = fopen(template, "w");
         ...
       }


File: libc.info,  Node: mktime,  Next: modf,  Prev: mktemp,  Up: Alphabetical List

mktime
======

Syntax
------

     #include <time.h>

     time_t mktime(struct tm *tptr);

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
TPTR.  The layout of a `struct tm' is as follows:

     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 */
     };

If you don't know whether daylight saving is in effect at the moment
specified by the contents of TPTR, set the `tm_isdst' member to -1,
which will cause `mktime' to compute the DST flag using the data base
in the `zoneinfo' subdirectory of your main DJGPP installation.  This
requires that you set the environment variable `TZ' to a file in that
directory which corresponds to your geographical area.

Return Value
------------

The resulting time, or -1 if the time in TPTR cannot be described in
that format.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: modf,  Next: modfl,  Prev: mktime,  Up: Alphabetical List

modf
====

Syntax
------

     #include <math.h>

     double modf(double x, double *pint);

Description
-----------

`modf' breaks down X into its integer portion (which it stores in
*PINT) and the remaining fractional portion, which it returns.  Both
integer and fractional portions have the same sign as X, except if X is
a negative zero, in which case the integer part is a positive zero.

Return Value
------------

The fractional portion.  If X is `Inf' or `NaN', the return value is
zero, the integer portion stored in *PINT is the same as the value of
X, and `errno' is set to `EDOM'.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: modfl,  Next: moncontrol,  Prev: modf,  Up: Alphabetical List

modfl
=====

Syntax
------

     #include <math.h>

     long double modfl(long double x, long double *pint);

Description
-----------

`modfl' breaks down X into its integer portion (which it stores in
*PINT) and the remaining fractional portion, which it returns.

Return Value
------------

The fractional portion.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: moncontrol,  Next: _mono_clear,  Prev: modfl,  Up: Alphabetical List

moncontrol
==========

Syntax
------

     #include <sys/gmon.h>

     int moncontrol (int mode);

Description
-----------

This function allows to control collection of profiling information
during the program run.  Profiling begins when a program linked with the
`-pg' option starts, or when `monstartup' is called (*note
monstartup::).  To stop the collection of histogram ticks and function
call counts, call `moncontrol' with a zero argument MODE; this stops
the timer used to sample the program counter (`EIP') values and
disables the code which counts how many times each function compiled
with `-pg' was called.  To resume collection of profile data, call
`moncontrol' with a non-zero argument.

Note that the profiling output is always written to the file `gmon.out'
at program exit time, regardless of whether profiling is on or off.

Return Value
------------

`moncontrol' returns the previous state of profiling: zero if it was
turned off, non-zero if it was on.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: _mono_clear,  Next: _mono_printf,  Prev: moncontrol,  Up: Alphabetical List

_mono_clear
===========

Syntax
------

     #include <sys/mono.h>

     void _mono_clear(void);

Description
-----------

Clears the monochrome monitor.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _mono_printf,  Next: _mono_putc,  Prev: _mono_clear,  Up: Alphabetical List

_mono_printf
============

Syntax
------

     #include <sys/mono.h>

     void _mono_printf(const char *fmt, ...);

Description
-----------

Like *Note printf::, but prints to the monochrome monitor.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _mono_putc,  Next: monstartup,  Prev: _mono_printf,  Up: Alphabetical List

_mono_putc
==========

Syntax
------

     #include <sys/mono.h>

     void _mono_putc(int c);

Description
-----------

Prints a single character to the monochrome monitor.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: monstartup,  Next: movedata,  Prev: _mono_putc,  Up: Alphabetical List

monstartup
==========

Syntax
------

     #include <sys/gmon.h>

     int monstartup (unsigned long lowpc, unsigned long highpc);

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 LOWPC and the
highest is just below HIGHPC.  `monstartup' arranges for the profiling
data to be gathered and written at program exit time, and then calls
the `moncontrol' function (*note moncontrol::) to start profiling.

The call graph printed by the `gprof' utility will only include
functions in this range compiled with the `-pg' option, but `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 `-pg' linker switch.  If `-pg' _was_ used during linking,
`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 `-pg', this function always fails, since the
startup code already called it.)  This is because `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
`moncontrol' (*note moncontrol::) to turn profiling off and on.

Return Value
------------

Zero on success, non-zero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

*Note moncontrol::.


File: libc.info,  Node: movedata,  Next: movedatab,  Prev: monstartup,  Up: Alphabetical List

movedata
========

Syntax
------

     #include <sys/movedata.h>

     void movedata(unsigned source_selector, unsigned source_offset,
                   unsigned dest_selector, unsigned dest_offset,
                   size_t length);

Description
-----------

This function allows the caller to directly transfer information
between conventional and linear memory, and among each as well.  The
selectors passed are _not_ segment values like in DOS.  They are
protected mode selectors that can be obtained by the `_my_ds' and
`_go32_info_block.selector_for_linear_memory' (or just `_dos_ds', which
is defined in the include file go32.h) functions (*Note _my_ds::, *note
_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 `(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
`segment'*16+`offset'.  For example, the color text screen buffer is at
offset 0xb8000.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: movedatab,  Next: movedatal,  Prev: movedata,  Up: Alphabetical List

movedatab
=========

Syntax
------

     #include <sys/movedata.h>

     void _movedatab(unsigned, unsigned, unsigned, unsigned, size_t);

Description
-----------

Just like *Note movedata::, but all transfers are always 8-bit
transfers.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: movedatal,  Next: movedataw,  Prev: movedatab,  Up: Alphabetical List

movedatal
=========

Syntax
------

     #include <sys/movedata.h>

     void _movedatal(unsigned, unsigned, unsigned, unsigned, size_t);

Description
-----------

Just like *Note movedata::, but all transfers are always 32-bit
transfers, and the count is a count of transfers, not bytes.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: movedataw,  Next: movetext,  Prev: movedatal,  Up: Alphabetical List

movedataw
=========

Syntax
------

     #include <sys/movedata.h>

     void _movedataw(unsigned, unsigned, unsigned, unsigned, size_t);

Description
-----------

Just like *Note movedata::, but all transfers are always 16-bit
transfers, and the count is a count of transfers, not bytes.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: movetext,  Next: mprotect,  Prev: movedataw,  Up: Alphabetical List

movetext
========

Syntax
------

     #include <conio.h>

     int movetext(int _left, int _top, int _right, int _bottom,
                  int _destleft, int _desttop);

Description
-----------

Moves a block of text on the screen.

Return Value
------------

1 on success, zero on error.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: mprotect,  Next: _my_cs,  Prev: movetext,  Up: Alphabetical List

mprotect
========

Syntax
------

     #include <sys/types.h>
     #include <sys/mman.h>

     int mprotect(void *addr, size_t len, int prot);

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 ADDR and LEN
should be multiples of 4096.

The protection 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.

Return Value
------------

The function returns 0 if successful and the value -1 if all the pages
could not be set.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     mprotect(readonly_buffer,8192,PROT_READ);
     mprotect(guard_area,4096,PROT_NONE);
     mprotect(NULL,4096,PROT_WRITE); /* Let NULL pointers not generate
                                      * exceptions */


File: libc.info,  Node: _my_cs,  Next: _my_ds,  Prev: mprotect,  Up: Alphabetical List

_my_cs
======

Syntax
------

     #include <sys/segments.h>

     unsigned short _my_cs();

Description
-----------

Returns the current `CS'.  This is useful for setting up interrupt
vectors and such.

Return Value
------------

`CS'

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _my_ds,  Next: _my_ss,  Prev: _my_cs,  Up: Alphabetical List

_my_ds
======

Syntax
------

     #include <sys/segments.h>

     unsigned short _my_ds();

Description
-----------

Returns the current `DS'.  This is useful for setting up interrupt
vectors and such.

Return Value
------------

`DS'

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _my_ss,  Next: nan,  Prev: _my_ds,  Up: Alphabetical List

_my_ss
======

Syntax
------

     #include <sys/segments.h>

     unsigned short _my_ss();

Description
-----------

Returns the current `SS'.  This is useful for setting up interrupt
vectors and such.

Return Value
------------

`SS'

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: nan,  Next: nanf,  Prev: _my_ss,  Up: Alphabetical List

nan
===

Syntax
------

     #include <math.h>

     double nan(const char *tagp);

Description
-----------

`nan' returns a quiet NaN with contents indicated by TAGP.

Return Value
------------

The quiet NaN.

If quiet NaNs are not supported, zero is returned. DJGPP supports quiet
NaNs.

Portability
-----------

ANSI/ISO C   C99; not C89

Example
-------

     double d = nan("0x1234");


File: libc.info,  Node: nanf,  Next: nanl,  Prev: nan,  Up: Alphabetical List

nanf
====

Syntax
------

     #include <math.h>

     float nanf(const char *tagp);

Description
-----------

`nanf' returns a quiet NaN with contents indicated by TAGP.

Return Value
------------

The quiet NaN.

If quiet NaNs are not supported, zero is returned. DJGPP supports quiet
NaNs.

Portability
-----------

ANSI/ISO C   C99; not C89

Example
-------

     float f = nanf("0x1234");


File: libc.info,  Node: nanl,  Next: nice,  Prev: nanf,  Up: Alphabetical List

nanl
====

Syntax
------

     #include <math.h>

     long double nanl(const char *tagp);

Description
-----------

`nanl' returns a quiet NaN with contents indicated by TAGP.

Return Value
------------

The quiet NaN.

If quiet NaNs are not supported, zero is returned. DJGPP supports quiet
NaNs.

Portability
-----------

ANSI/ISO C   C99; not C89

Example
-------

     long double ld = nanl("0x1234");


File: libc.info,  Node: nice,  Next: normvideo,  Prev: nanl,  Up: Alphabetical List

nice
====

Syntax
------

     #include <unistd.h>

     int nice(int _increment);

Description
-----------

Adjusts the priority of the process.  Provided for Unix compatibility
only.

Return Value
------------

The new nice value.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: normvideo,  Next: nosound,  Prev: nice,  Up: Alphabetical List

normvideo
=========

Syntax
------

     #include <conio.h>

     void normvideo(void);

Description
-----------

Resets the text attribute to what it was before the program started.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: nosound,  Next: ntohl,  Prev: normvideo,  Up: Alphabetical List

nosound
=======

Syntax
------

     #include <pc.h>

     void nosound(void);

Description
-----------

Disable the PC speaker.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: ntohl,  Next: ntohs,  Prev: nosound,  Up: Alphabetical List

ntohl
=====

Syntax
------

     #include <netinet/in.h>

     unsigned long ntohl(unsigned long val);

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.

Return Value
------------

The host-order value.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     ip = ntohl(packet.ipaddr);


File: libc.info,  Node: ntohs,  Next: open,  Prev: ntohl,  Up: Alphabetical List

ntohs
=====

Syntax
------

     #include <netinet/in.h>

     unsigned short ntohs(unsigned short val);

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.

Return Value
------------

The host-order value.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     port = ntohs(tcp.port);


File: libc.info,  Node: open,  Next: _open,  Prev: ntohs,  Up: Alphabetical List

open
====

Syntax
------

     #include <fcntl.h>    /* provides mode definitions */
     #include <sys/stat.h> /* provides permission definitions */

     int open(const char *file, int mode /*, int permissions */);

Description
-----------

This function opens the named FILE in the given MODE, which is any
combination of the following bits:

`O_RDONLY'
     The file is opened for reading.

`O_WRONLY'
     The file is opened for writing.

`O_RDWR'
     The file is opened for both reading and writing.

`O_CREAT'
     If the file does not exist, it is created. *Note creat::.

`O_TRUNC'
     If the file does exist, it is truncated to zero bytes.

`O_EXCL'
     If the file exists, and `O_CREAT' is also specified, the `open'
     call will fail.  If the file is a symlink and `O_CREAT' is also
     specified, then the contents of the symlink are ignored - the
     `open' call will fail.

`O_APPEND'
     The file pointer is positioned at the end of the file before each
     write.

`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 `_fmode' variable *Note _fmode::.

`O_BINARY'
     The file is opened in binary mode.

     When called to open the console in binary mode, `open' will disable
     the generation of `SIGINT' when you press `Ctrl-C' (`Ctrl-Break'
     will still cause `SIGINT'), because many programs that use binary
     reads from the console will also want to get the `^C' characters.
     You can use the `__djgpp_set_ctrl_c' library function (*note
     __djgpp_set_ctrl_c::) if you want `Ctrl-C' to generate interrupts
     while console is read in binary mode.

`O_NOINHERIT'
     Child processes will not inherit this file handle.  This is also
     known as "close-on-exec"-see *Note fcntl::.  This bit is DOS- and
     Windows-specific; portable programs should use `fcntl' instead.

`O_NOFOLLOW'
     `open' will fail with `errno' set to `ELOOP', if the last path
     component in FILE is symlink.

`O_NOLINK'
     If FILE is a symlink, `open' will open symlink file itself instead
     of referred file.

`O_TEMPORARY'
     Delete FILE when all file descriptors that refer to it are closed.

     Note that FILE should not also be opened with the low-level
     functions `_creat', `_creatnew', `_dos_creat', `_dos_creatnew',
     and `_dos_open'.  Otherwise FILE may not be deleted as expected.


If the file is created by this call, it will be given the read/write
permissions specified by PERMISSIONS, which may be any combination of
these values:

`S_IRUSR'
     The file is readable.  This is always true for MS-DOS.

`S_IWUSR'
     The file is writable.


Other `S_I*' values may be included, but they will be ignored.

You can specify the share flags (a DOS specific feature) in MODE.  And
you can indicate default values for the share flags in
`__djgpp_share_flags'. *Note __djgpp_share_flags::.

You can open directories using `open', but there is limited support for
POSIX file operations on directories.  In particular, directories
cannot be read using `read' (*note read::) or written using `write'
(*note write::).  The principal reason for allowing `open' to open
directories is to support changing directories using `fchdir' (*note
fchdir::).  If you wish to read the contents of a directory, use the
`opendir' (*note opendir::) and `readdir' (*note readdir::) functions
instead.  File descriptors for directories are not inherited by child
programs.

Return Value
------------

If successful, the file descriptor is returned.  On error, a negative
number is returned and `errno' is set to indicate the error.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     int q = open("/tmp/foo.dat", O_RDONLY|O_BINARY);


File: libc.info,  Node: _open,  Next: opendir,  Prev: open,  Up: Alphabetical List

_open
=====

Syntax
------

     #include <io.h>

     int _open(const char *path, int attrib);

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 `_open' calls function int 0x21, %ax = 0x6c00. When long file
names are supported, `_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 ATTRIB parameter is a combination of one or more bits from the
following:

`O_RDONLY'
     open for read only

`O_WRONLY'
     open for write only

`O_RDWR'
     open for read and write

`O_NOINHERIT'
     file handle is not inherited by child processes

`SH_COMPAT'
     open in compatibility mode

`SH_DENYRW'
     deny requests by other processes to open the file for eaither
     reading or writing

`SH_DENYWR'
     deny requests to open the file for writing

`SH_DENYRD'
     deny requests to open the file for reading

`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

This function can be hooked by File System Extensions (*note File
System Extensions::).  If you don't want this, you should use
`_dos_open' (*note _dos_open::) (but note that the latter doesn't
support long file names).

Return Value
------------

The new file descriptor, else -1 on error.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: opendir,  Next: outb,  Prev: _open,  Up: Alphabetical List

opendir
=======

Syntax
------

     #include <dirent.h>

     extern int __opendir_flags;

     DIR *opendir(char *name);

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 `closedir' when
you are done with it.  *Note readdir::.

The global variable `__opendir_flags' can be set to include the
following values to control the operation of `opendir':

`__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
     `README' and `FAQ' from Unix distributions to be returned in
     upper-case on Windows 9X filesystems.  *Note _preserve_fncase::,
     for other ways of achieving this and for more detailed description
     of the automatic letter-case conversion by DJGPP library functions.

`__OPENDIR_NO_HIDDEN'
     Do not include hidden files and directories in the search.  By
     default, all files and directories are included.

`__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.

`__OPENDIR_FIND_LABEL'
     Include volume labels in the search.  By default, these are
     skipped.

`__OPENDIR_NO_D_TYPE'
     Do not compute the `d_type' member of `struct dirent'.  If this
     flag is set, all files will get `DT_UNKNOWN' in the `d_type'
     member.  By default, this flag is reset.  *Note readdir::.

You can simply put `int __opendir_flags = ...;' in your code.  The
default is to let it get set to zero as an uninitialized variable.

Return Value
------------

The open directory structure, or `NULL' on error.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)

Notes:

  1. The `__opendir_flags' variable is DJGPP-specific.

Example
-------

     DIR *d = opendir(".");
     closedir(d);


File: libc.info,  Node: outb,  Next: outp,  Prev: opendir,  Up: Alphabetical List

outb
====

Syntax
------

     #include <pc.h>

     void outb(unsigned short _port, unsigned char _data);

Description
-----------

Calls *Note outportb::. Provided only for compatibility.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: outp,  Next: outportb,  Prev: outb,  Up: Alphabetical List

outp
====

Syntax
------

     #include <pc.h>

     void outp(unsigned short _port, unsigned char  _data);

Description
-----------

Calls *Note outportb::. Provided only for compatibility.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: outportb,  Next: outportl,  Prev: outp,  Up: Alphabetical List

outportb
========

Syntax
------

     #include <pc.h>

     void outportb(unsigned short _port, unsigned char  _data);

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.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: outportl,  Next: outportsb,  Prev: outportb,  Up: Alphabetical List

outportl
========

Syntax
------

     #include <pc.h>

     void outportl(unsigned short _port, unsigned long _data);

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.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: outportsb,  Next: outportsl,  Prev: outportl,  Up: Alphabetical List

outportsb
=========

Syntax
------

     #include <pc.h>

     void outportsb(unsigned short _port,
                    const unsigned char *_buf, unsigned _len);

Description
-----------

Writes the _LEN bytes in _BUF to the 8-bit _PORT.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: outportsl,  Next: outportsw,  Prev: outportsb,  Up: Alphabetical List

outportsl
=========

Syntax
------

     #include <pc.h>

     void outportsl(unsigned short _port,
                    const unsigned long *_buf, unsigned _len);

Description
-----------

Writes the _LEN longs in _BUF to the 32-bit _PORT.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: outportsw,  Next: outportw,  Prev: outportsl,  Up: Alphabetical List

outportsw
=========

Syntax
------

     #include <pc.h>

     void outportsw(unsigned short _port,
                    const unsigned short *_buf, unsigned _len);

Description
-----------

Writes the _LEN shorts in _BUF to the 16-bit _PORT.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: outportw,  Next: outpw,  Prev: outportsw,  Up: Alphabetical List

outportw
========

Syntax
------

     #include <pc.h>

     void outportw(unsigned short _port, unsigned short _data);

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.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: outpw,  Next: pathconf,  Prev: outportw,  Up: Alphabetical List

outpw
=====

Syntax
------

     #include <pc.h>

     void outpw(unsigned short _port, unsigned short _data);

Description
-----------

Calls *Note outportw::. Provided only for compatibility.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: pathconf,  Next: pause,  Prev: outpw,  Up: Alphabetical List

pathconf
========

Syntax
------

     #include <unistd.h>

     long pathconf(const char *filename, int name);

Description
-----------

This function returns various system-dependent configuration values.
The NAME is one of the following:

`_PC_LINK_MAX'
     The maximum number of directory entries that can refer to a single
     real file.  Always 1 in DJGPP.

`_PC_MAX_CANON'
     The maximum number of bytes in an editable input line.  In DJGPP,
     this is 126 (DOS restriction).

`_PC_MAX_INPUT'
     The maximum number of bytes in a non-editable input line.  Also
     126 in DJGPP.

`_PC_NAME_MAX'
     The maximum length of an individual file name.  If the filesystem
     where FILENAME resides supports long file names, the result is
     whatever `_get_volume_info' returns (usually 255); otherwise 12
     will be returned.  *Note _use_lfn::.

`_PC_PATH_MAX'
     The maximum length of a complete path name.  If the filesystem
     where FILENAME resides supports long file names, the result is
     whatever `_get_volume_info' returns (usually 260); otherwise 80
     will be returned.  *Note _use_lfn::.

`_PC_PIPE_BUF'
     The size of a pipe's internal buffer.  In DJGPP, this returns 512.

`_PC_CHOWN_RESTRICTED'
     If non-zero, only privileged user can change the ownership of
     files by calling `chown', otherwise anyone may give away files.
     The DJGPP version always returns zero, since MS-DOS files can be
     freely given away.

`_PC_NO_TRUNC'
     If zero is returned, filenames longer than what
     `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.

`_PC_VDISABLE'
     A character to use to disable tty special characters.  DJGPP
     currently doesn't support special characters, so this returns -1.


Return Value
------------

The selected configuration value is returned.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     char *buf = malloc(pathconf("c:/", _PC_MAX_PATH)+1);


File: libc.info,  Node: pause,  Next: pclose,  Prev: pathconf,  Up: Alphabetical List

pause
=====

Syntax
------

     #include <unistd.h>

     int pause(void);

Description
-----------

This function just calls `__dpmi_yield()' (*note __dpmi_yield::) to
give up a slice of the CPU.

Return Value
------------

Zero.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: pclose,  Next: perror,  Prev: pause,  Up: Alphabetical List

pclose
======

Syntax
------

     #include <stdio.h>

     int pclose(FILE *pipe);

Description
-----------

This function closes a pipe opened with `popen' (*note popen::).  Note
that since MS-DOS is not multitasking, this function will actually run
the program specified in `popen' if the pipe was opened for writing.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     FILE *f = popen("sort", "w");
     write_to_pipe(f);
     pclose(f);


File: libc.info,  Node: perror,  Next: pipe,  Prev: pclose,  Up: Alphabetical List

perror
======

Syntax
------

     #include <stdio.h>

     void perror(const char *string);

Description
-----------

This function formats an error message and prints it to `stderr'.  The
message is the STRING, a colon and a blank, and a message suitable for
the error condition indicated by `errno'.  If STRING is a null pointer
or points to a null string, the colon and blank are not printed.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     int x = open("foo", O_RDONLY);
     if (x < 0)
     {
       perror("foo");
       exit(1);
     }


File: libc.info,  Node: pipe,  Next: popen,  Prev: perror,  Up: Alphabetical List

pipe
====

Syntax
------

     #include <unistd.h>

     int pipe(int fildes[2]);

Description
-----------

This function creates a pipe and places a file descriptor for the read
end of the pipe in `FILDES[0]', and another for the write end in
`FILDES[1]'.  Data written to `FILDES[1]' will be read from `FILDES[0]'
on a first-in first-out (FIFO) basis.

Note this pipe implementation won't help port instances of
`fork'/`exec' or any other methods that require support for
multitasking.

Return Value
------------

Zero for success, otherwise -1 is returned and `errno' is set to
indicate the error.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

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;
     }


File: libc.info,  Node: popen,  Next: pow,  Prev: pipe,  Up: Alphabetical List

popen
=====

Syntax
------

     #include <stdio.h>

     FILE *popen(const char *cmd, const char *mode);

Description
-----------

This function executes the command or program specified by `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
`pclose' (*note 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.  `pclose' then removes that file.
Similarly, when you open a program for writing, a temp file holds the
data and `pclose' runs the entire program.

The MODE is the same as for `fopen' (*note 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.

Return Value
------------

An open file which can be used to read the program's output or write to
the program's input.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     FILE *p = popen("dir", "r");
     read_program(p);
     pclose(p);


File: libc.info,  Node: pow,  Next: pow10,  Prev: popen,  Up: Alphabetical List

pow
===

Syntax
------

     #include <math.h>

     double pow(double x, double y);

Description
-----------

This function computes X^Y, X raised to the power Y.

Return Value
------------

X raised to the power Y.  If the result overflows a `double' or
underflows, `errno' is set to `ERANGE'.  If Y is `NaN', the return
value is `NaN' and `errno' is set to `EDOM'.  If X and Y are both 0,
the return value is 1, but `errno' is set to `EDOM'.  If Y is a
positive or a negative Infinity, the following results are returned,
depending on the value of X:

X negative
     the return value is `NaN' and `errno' is set to `EDOM'.

absolute value of X less than 1 and Y is `+Inf'
absolute value of X greater than 1 and Y is `-Inf'
     the return value is zero.

absolute value of X less than 1 and Y is `-Inf'
absolute value of X greater than 1 and Y is `+Inf'
     the return value is `+Inf'.

absolute value of X is 1
     the return value is `NaN' and `errno' is set to `EDOM'.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: pow10,  Next: pow2,  Prev: pow,  Up: Alphabetical List

pow10
=====

Syntax
------

     #include <math.h>

     double pow10(double x);

Description
-----------

This function computes 10 to the power of X, 10^x.

Return Value
------------

10 to the X power.  If the value of X is finite, but so large in
magnitude that 10^x cannot be accurately represented by a `double', the
return value is the nearest representable !  `double' (possibly, an
`Inf'), and `errno' is set to `ERANGE'.  If X is either a positive or a
negative infinity, the result is either `+Inf' or zero, respectively,
and `errno' is not changed.  If X is a `NaN', the return value is `NaN'
and `errno' is set to `EDOM'.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: pow2,  Next: powi,  Prev: pow10,  Up: Alphabetical List

pow2
====

Syntax
------

     #include <math.h>

     double pow2(double x);

Description
-----------

This function computes 2 to the power of X, 2^x.

Return Value
------------

2 to the X power.  If the value of X is finite, but so large in
magnitude that 2^x cannot be accurately represented by a `double', the
return value is the nearest representable `double' (possibly, an
`Inf'), and `errno' is set to `ERANGE'.  If X is either a positive or a
negative infinity, the result is either `+Inf' or zero, respectively,
and `errno' is not changed.  If X is a `NaN', the return value is `NaN'
and `errno' is set to `EDOM'.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: powi,  Next: _preserve_fncase,  Prev: pow2,  Up: Alphabetical List

powi
====

Syntax
------

     #include <math.h>

     double powi(double x, int iy);

Description
-----------

This function computes x^iy, where 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 `powi' than to call
`pow' with the same arguments, even if IY has a very large value.  For
small values of IY, `powi' is _much_ faster than `pow'.

Return Value
------------

X raised to the IY power.  If X and IY are both zero, the return value
is 1.  If X is equal to zero, and IY is negative, the return value is
`Inf'.  This function never sets `errno'.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _preserve_fncase,  Next: PRI,  Prev: powi,  Up: Alphabetical List

_preserve_fncase
================

Syntax
------

     #include <fcntl.h>

     char _preserve_fncase (void);

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 `readdir', `_fixpath' and others).  The
usual behavior of these functions (when `_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 (*note
_use_lfn::).  This can be changed by either setting
`_CRT0_FLAG_PRESERVE_FILENAME_CASE' bit in the `_crt0_startup_flags'
variable (*note _crt0_startup_flags::), or by setting the `FNCASE'
environment variable to `Y' at run time.  You might need such a setup
e.g. on Windows 95 if you want to see files with names like `README'
and `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
`LFN' is set to `N' on systems that support LFN.  That is because this
is how filenames are stored in the DOS directory entries.

Return value
------------

Zero when 8+3 filenames should be converted to lower-case, non-zero
otherwise.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: PRI,  Next: printf,  Prev: _preserve_fncase,  Up: Alphabetical List

PRI
===

Syntax
------

     #include <inttypes.h>

Description
-----------

The `PRI' family of macros allows integers to be displayed in a
portable manner using the `printf' family of functions (*note
printf::).  They include a conversion qualifier, to specify the width
of the type (e.g.: `l' for `long'), and the conversion type specifier
(e.g.: `d' for decimal display of integers).

The `PRI' family of macros should be used with the types defined in the
header `<stdint.h>'.  For example: `int8_t', `uint_fast32_t',
`uintptr_t', `intmax_t'.

Below N can be 8, 16, 32 or 64.  The `PRI' macros are:

`PRIdN'
`PRIiN'
     The `d' and `i' type conversion specifiers for a type `intN_t' of
     N bits.

`PRIdLEASTN'
`PRIiLEASTN'
     The `d' and `i' type conversion specifiers for a type
     `int_leastN_t' of N bits.

`PRIdFASTN'
`PRIiFASTN'
     The `d' and `i' type conversion specifiers for a type
     `int_fastN_t' of N bits.

`PRIdMAX'
`PRIiMAX'
     The `d' and `i' type conversion specifiers for a type `intmax_t'.

`PRIdPTR'
`PRIiPTR'
     The `d' and `i' type conversion specifier for a type `intptr_t'.

`PRIoN'
`PRIuN'
`PRIxN'
`PRIXN'
     The `o', `u', `x' and `X' type conversion specifiers for a type
     `uintN_t' of N bits.

`PRIoLEASTN'
`PRIuLEASTN'
`PRIxLEASTN'
`PRIXLEASTN'
     The `o', `u', `x' and `X' type conversion specifiers for a type
     `uint_LEASTN_t' of N bits.

`PRIoFASTN'
`PRIuFASTN'
`PRIxFASTN'
`PRIXFASTN'
     The `o', `u', `x' and `X' type conversion specifiers for a type
     `uint_FASTN_t' of N bits.

`PRIoMAX'
`PRIuMAX'
`PRIxMAX'
`PRIXMAX'
     The `o', `u', `x' and `X' type conversion specifiers for a type
     `uintmax_t'.

`PRIoPTR'
`PRIuPTR'
`PRIxPTR'
`PRIXPTR'
     The `o', `u', `x' and `X' type conversion specifiers for a type
     `uintptr_t'.


Return Value
------------

Not applicable.

Portability
-----------

ANSI/ISO C   C99; not C89
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992

Example
-------

     uintmax_t foo = 500;

     printf("foo is %" PRIuMAX " in decimal and 0x%" PRIxMAX " in hex.\n",
            foo, foo);


File: libc.info,  Node: printf,  Next: psignal,  Prev: PRI,  Up: Alphabetical List

printf
======

Syntax
------

     #include <stdio.h>

     int printf(const char *format, ...);

Description
-----------

Sends formatted output from the arguments (...) to `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 Nth argument after the format string in the
argument list, rather than to the next unused argument.  In this case,
the conversion specifier character `%' is replaced by the sequence
`%N$', where N is a decimal integer in the range [`1', `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, `%N$' and `*M$'), or unnumbered
argument conversion specifiers (that is `%' and `*'), but not both.
The only exception to this is that `%%' can be mixed with `%N$' form.
When numbered argument specifications are used, specifying the Nth
argument requires that all the leading arguments, from the first to the
(N-1)th, are specified in the format string.  In format strings
containing the `%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:

   *  an optional flag, which may alter the conversion:

    `''
          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.

    `-'
          left-justify the field.

    `+'
          Force a `+' sign on positive numbers.

    `space'
          To leave a blank space where a plus or minus sign would have
          been.

    `#'
          Alternate conversion - prefix octal numbers with `0',
          hexadecimal numbers with `0x' or `0X', or force a trailing
          decimal point if a floating point conversion would have
          omitted it.

    `0'
          To pad numbers with leading zeros.


   *  A field width specifier, which specifies the minimum width of the
     field.  This may also be an asterisk (`*'), which means that the
     actual width will be obtained from the next argument.  If the
     argument is negative, it supplies a `-' flag and a positive width.
     In format strings containing the `%N$' form of a conversion
     specifier, a field width can be indicated by the sequence `*M$',
     where M is a decimal integer in the range [`1', `number of the
     last argument'], giving the position in the argument list (after
     the format argument) of an integer argument containing the field
     width.

   *  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 `g' or `G', actual for others), or the
     maximum number of characters for a string.  In format strings
     containing the `%N$' form of a conversion specifier, a precision
     can be indicated by the sequence `*M$', where M is a decimal
     integer in the range [`1', `number of the last argument'], giving
     the position in the argument list (after the format argument) of
     an integer argument containing the precision.

   *  An optional conversion qualifier, which may be:

    `hh'
          to specify `char';

    `h'
          to specify `short' integers;

    `j'
          to specify `intmax_t' or `uintmax_t' integers;

    `l'
          to specify doubles or `long' integers, `wint_t' or `wchar_t';

    `ll'
          (two lower-case ell letters) to specify `long long' integers;
          to specify `long' doubles, although this is non-standard;

    `L'
          to specify `long' doubles;

    `t'
          to specify `ptrdiff_t';

    `z'
          to specify `size_t'.

   *  The conversion type specifier:

    `a'
    `A'
          A floating point number (float or double) printed in the style
          `"[-]0xh.hhhhp[+|-]d"', where `h' represents a hexadecimal
          digit, `d' represents a decimal digit and `p' stands for the
          base 2.  For long double, use `"La"' or `"LA"'.  The case of
          the exponent, the case of the letters `"abcdef"' and the case
          of `"x"' matches the specifier case.  The representation
          always has an exponent.

    `c'
          A single character.

    `d'
          A signed integer.

    `D'
          A signed long integer.  This is non-standard and obsolete.
          Please use `ld' instead.

    `e'
    `E'
          A floating point number (float or double).  For long double,
          use `"Le"' or `"LE"'.  The exponent case matches the specifier
          case.  The representation always has an exponent.

    `f'
    `F'
          A floating point number (float or double).  For long double,
          use `"Lf"'.  The representation never has an exponent.

    `g'
    `G'
          A floating point number (float or double).  For long double,
          use `"Lg"' or `"LG"'.  The exponent case matches the specifier
          case.  The representation has an exponent if it needs one.

    `i'
          A signed integer.

    `n'
          The next argument is a pointer to an integer, and the number
          of characters generated so far is stored in that integer.

    `o'
          A unsigned integer, printed in base 8 instead of base 10.

    `O'
          A unsigned long integer, printed in base 8 instead of base 10.
          This is non-standard and obsolete.  Please use `lo' instead.

    `p'
          A pointer.  This is printed with an `x' specifier.

    `s'
          A `NULL'-terminated string.

    `u'
          An unsigned integer.

    `U'
          An unsigned long integer.  This is non-standard and obsolete.
          Please use `lu' instead.

    `x'
    `X'
          An unsigned integer, printed in base 16 instead of base 10.
          The case of the letters used matches the specifier case.

    `%'
          A single percent symbol is printed.



Return Value
------------

The number of characters written.

Portability
-----------

ANSI/ISO C   C89; C99 (see note 1); (see note 2) (see note 3)
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Notes:

  1. The `hh', `j', `t' and `z' conversion qualifiers first appeared in
     the ANSI C99 standard.

  2. The `D', `O' and `U' conversion type specifiers are non-standard.
     gcc may generate warnings, if you use them.

  3. The `a', `A' and `F' conversion type specifiers first appeared in
     the ANSI C99 standard.


Example
-------

     printf("%-3d %10.2f%% Percent of %s\n", index, per[index], name[index]);

The following statement can be used to print date and time using
language-independent format:

     printf(format, weekday, month, day, hour, precision, min);

For American usage, the format string could look like:

     "%s, %s %d, %d:%.*d\n"

The integer precision has the value 2.  The above example will produce
the following message:

     Sunday, October 27, 9:09

For German usage, the format string could look like:

     "%1$s, %3$d. %2$s, %4$d:%6$.*5$d\n"

The above example will produce the following message:

     Sonntag, 27. Oktober, 9:09


File: libc.info,  Node: psignal,  Next: _put_path,  Prev: printf,  Up: Alphabetical List

psignal
=======

Syntax
------

     #include <signal.h>

     extern char *sys_siglist[];
     void psignal (int sig, const char *msg);

Description
-----------

This function produces a message on the standard error stream describing
the signal given by its number in SIG.  It prints the string pointed to
by MSG, then the name of the signal, and a newline.

The names of signals can be retrieved using the array `sys_siglist',
with the signal number serving as an index into this array.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

       #include <signal.h>

       void sig_catcher (int sig)
       {
         psignal (progname, sig);
         return;
       }


File: libc.info,  Node: _put_path,  Next: putc,  Prev: psignal,  Up: Alphabetical List

_put_path
=========

Syntax
------

     #include <libc/dosio.h>

     int _put_path(const char *path);
     int _put_path2(const char *path, int offset);

Description
-----------

These functions are used internally by all low-level library functions
that need to pass file names to DOS.  `_put_path' copies its argument
PATH to the "transfer buffer" (*note _go32_info_block::) starting at
the beginning of the transfer buffer; `_put_path2' does the same except
that it puts the file name starting at 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 `_put_path' or `_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 _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:

   * Multiple forward slashes are collapsed into a single slash.

     Unix treats multiple slashes as a single slash, so some ported
     programs pass names like `c:/foo//bar' to library functions.  DOS
     functions choke on such file names, so collapsing the slashes
     prevents these names from failing.

   * Trailing slashes are removed, except for root directories.

     Various DOS calls cannot cope with file names like `c:/foo/'; this
     feature solves this problem.

   * Translation of Unix device names.

     Unix `/dev/null' is mapped to DOS-standard `NUL', and Unix
     `/dev/tty' to DOS-standard `CON'.  This provides for transparent
     support of these special devices, e.g. in Unix shell scripts.

   * Translation of DOS device names.

     Any file name which begins with `/dev/' or `X:/dev/' (where X: is
     any valid DOS drive letter) has the `/dev/' or `X:/dev/' prefix
     removed (if the `/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 `/dev/con' to a fully-qualified path name.
     Because of the different behavior when the `/dev/' directory
     exists, you should only add the prefix `/dev/' to your DOS device
     names if necessary and be sure that the `/dev/' does not exist.
     Due to the additional overhead of checking if `/dev/' exists,
     functions working with DOS device names with the prefix will be
     slower.

   * `/dev/x/' is translated into `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. `/dev/c/' where
     `c:/' would fail.

   * `/dev/env/FOO/' is replaced by the value of the environment
     variable FOO.

     (In other words, you can think of environment variables as if they
     were sub-directories of a fictitious directory `/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, `/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 `DJDIR' is computed by the DJGPP startup code and
     pushed into the environment of every DJGPP program before `main'
     is called.)

     Note that environment variables are case-sensitive, so
     `/dev/env/foo' and `/dev/env/FOO' are *not* the same.  DOS shells
     usually upcase the name of the environment variable if you set it
     with the built-in command `SET', so if you type e.g. `SET
     foo=bar', the shell defines a variable named `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
     `/dev/env/' notation.  For example, if the variable `HOME' is set
     to `/dev/env/DJDIR/home', and DJGPP is installed in
     `c:/software/djgpp', then `/dev/env/HOME/sources' will expand to
     `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
     `~', like in `/dev/env/DJDIR~c:/djgpp~/include'.

     If you need to include a literal character `~' in either the
     environment variable name or in the default value that replaces
     it, use two `~'s in a row.  For example, `/dev/env/FOO~~' will
     expand to the value of the variable `FOO~'.  Likewise,
     `/dev/env/FOO~~BAR~foo~~baz~' will expand to the value of the
     variable `FOO~BAR' if it is defined and nonempty, and to `foo~baz'
     otherwise.  Leading `~' 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,
     `/dev/env/foo~/dev/env/bar~' will work, but
     `/dev/env/foo~/dev/env/bar~baz~~' will *not*.  To use nested
     default values, you need to double the quoting of the `~'
     characters, like in `/dev/env/foo~/dev/env/bar~~baz~~~'.

Return Value
------------

Both functions return the offset into the transfer buffer of the
terminating null character that ends the file name.

ANSI/ISO C   No
POSIX        No

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 `_put_path' or `_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 _have_ been warned!

      __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);


File: libc.info,  Node: putc,  Next: putch,  Prev: _put_path,  Up: Alphabetical List

putc
====

Syntax
------

     #include <stdio.h>

     int putc(int c, FILE *file);

Description
-----------

This function writes one character to the given FILE.

Return Value
------------

The character written.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     while ((c=getc(stdin)) != EOF)
       putc(c, stdout);


File: libc.info,  Node: putch,  Next: putchar,  Prev: putc,  Up: Alphabetical List

putch
=====

Syntax
------

     #include <conio.h>

     int putch(int _c);

Description
-----------

Put the character _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.

Return Value
------------

The character is returned.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: putchar,  Next: putenv,  Prev: putch,  Up: Alphabetical List

putchar
=======

Syntax
------

     #include <stdio.h>

     int putchar(int c);

Description
-----------

This is the same as `fputc(c, stdout)'.  *Note fputc::.

Return Value
------------

The character written.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     while ((c = getchar()) != EOF)
       putchar(c);


File: libc.info,  Node: putenv,  Next: puts,  Prev: putchar,  Up: Alphabetical List

putenv
======

Syntax
------

     #include <stdlib.h>

     int putenv(char *env);

Description
-----------

This function adds an entry to the program's environment.  The string
passed must be of the form `NAME'=`VALUE'.  Any existing value for the
environment variable is gone.

`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.

Return Value
------------

Zero on success, nonzero on failure;  `errno' will be set to the
relevant error code: currently only `ENOMEM' (insufficient memory) is
possible.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)

Notes:

  1. This function is new to the Posix 1003.1-200x draft

Example
-------

     putenv("SHELL=ksh.exe");


File: libc.info,  Node: puts,  Next: puttext,  Prev: putenv,  Up: Alphabetical List

puts
====

Syntax
------

     #include <stdio.h>

     int puts(const char *string);

Description
-----------

This function writes STRING to `stdout', and then writes a newline
character.

Return Value
------------

Nonnegative for success, or `EOF' on error.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     puts("Hello, there");


File: libc.info,  Node: puttext,  Next: putw,  Prev: puts,  Up: Alphabetical List

puttext
=======

Syntax
------

     #include <conio.h>

     int puttext(int _left, int _top, int _right, int _bottom,
                 void *_source);

Description
-----------

The opposite of *Note gettext::.

Return Value
------------

1 on success, zero on error.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: putw,  Next: pwrite,  Prev: puttext,  Up: Alphabetical List

putw
====

Syntax
------

     #include <stdio.h>

     int putw(int x, FILE *file);

Description
-----------

Writes a single 32-bit binary word X in native format to FILE.  This
function is provided for compatibility with other 32-bit environments,
so it writes a 32-bit `int', not a 16-bit `short', like some 16-bit DOS
compilers do.

Return Value
------------

The value written, or `EOF' for end-of-file or error.  Since `EOF' is a
valid integer, you should use `feof' or `ferror' to detect this
situation.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     putw(12, stdout);


File: libc.info,  Node: pwrite,  Next: qsort,  Prev: putw,  Up: Alphabetical List

pwrite
======

Syntax
------

     #include <unistd.h>

     int pwrite(int file, const void *buffer, size_t count, off_t offset);

Description
-----------

This function writes COUNT bytes from BUFFER to FILE at position
OFFSET.  It returns the number of bytes actually written.  It will
return zero or a number less than COUNT if the disk is full, and may
return less than COUNT even under valid conditions.

Note that if FILE is a text file, `pwrite' may write more bytes than it
reports.

If COUNT is zero, the function does nothing and returns zero.  Use
`_write' if you want to actually ask DOS to write zero bytes.

The precise behavior of `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 `errno' being set to
`ENOSPC' in such cases, you need to invoke `pwrite' as shown in an
example for `write' (*note write::).  In a nutshell, the trick is to
call `pwrite' one more time after it returns a value smaller than the
COUNT parameter; then it will _always_ set `errno' if the disk is full.

Return Value
------------

The number of bytes written, zero at EOF, or -1 on error.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992

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);


File: libc.info,  Node: qsort,  Next: raise,  Prev: pwrite,  Up: Alphabetical List

qsort
=====

Syntax
------

     #include <stdlib.h>

     void qsort(void *base, size_t numelem, size_t size,
                int (*cmp)(const void *e1, const void *e2));

Description
-----------

This function sorts the given array in place.  BASE is the address of
the first of NUMELEM array entries, each of size SIZE bytes.  `qsort'
uses the supplied function 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:

Negative
     Element E1 should come before element E2 in the resulting array.

Positive
     Element E1 should come after element E2 in the resulting array.

Zero
     It doesn't matter which element comes first in the resulting array.


Return Value
------------

None.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

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);


File: libc.info,  Node: raise,  Next: rand,  Prev: qsort,  Up: Alphabetical List

raise
=====

Syntax
------

     #include <signal.h>

     int	raise(int sig);

Description
-----------

This function raises the given signal SIG.  *Note the list of possible
signals: signal.

Return Value
------------

0 on success, -1 for illegal value of SIG.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: rand,  Next: rand48,  Prev: raise,  Up: Alphabetical List

rand
====

Syntax
------

     #include <stdlib.h>

     int rand(void);

Description
-----------

Returns a pseudo-random number between zero and `RAND_MAX' (defined on
`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 `rand' by
calling `srand' (*note srand::) before the first call to `rand', and
make sure to use a different argument to `srand' each time.  The usual
technique is to get the argument to `srand' from a call to the `time'
library function (*note time::), whose return value changes every
second.

To get a random number in the range 0..N, use `rand()%(N+1)'.  Note
that the low bits of the `rand''s return value are not very random, so
`rand()%N' for small values of N could be not enough random.  The
alternative, but non-ANSI, function `random' is better if N is small.
*Note random::.

Return Value
------------

The number.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     /* random pause */
     srand(time(0));
     for (i=rand(); i; i--);


File: libc.info,  Node: rand48,  Next: random,  Prev: rand,  Up: Alphabetical List

rand48
======

Syntax
------

     #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]);

Description
-----------

This is the family of `*rand48' functions.  The basis for these
functions is the linear congruential formula 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 `srand48' or `seed48'.  A call to `lcong48' changes a and c (and
the internal state).

`drand48' and `erand48' return `double's uniformly distributed in the
interval [0.0, 1.0).

`lrand48' and `nrand48' return `unsigned long's uniformly distributed
in the interval [0, 2^31).

`mrand48' and `jrand48' return `long's uniformly distributed in the
interval [-2^31, 2^31).

`erand48', `jrand48' and `nrand48' requires the state of the random
generator to be passed.

`drand48', `lrand48' and `mrand48' uses an internal state (common with
all three functions) which should be initialized with a call to one of
the functions `srand48', `seed48' or `lcong48'.

`srand48' sets the high order 32 bits to the argument SEED.  The low
order 16 bits are set to the arbitrary value 0x330e.

`seed48' sets the internal state according to the argument STATE_SEED
(`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.

`lcong48' sets the internal state to `PARAM[0-2]', a to `PARAM[3-5]'
(`PARAM[0]' and `PARAM[3]' are least significant) and c to `PARAM[6]'.

Return Value
------------

A random number.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);
     }


File: libc.info,  Node: random,  Next: rawclock,  Prev: rand48,  Up: Alphabetical List

random
======

Syntax
------

     #include <stdlib.h>

     long random(void);

Description
-----------

Returns a random number in the range 0..MAXINT.

Return Value
------------

0 .. MAXINT

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

      /* Produce a random integer between 0 and 199.  */
      int random_number = random () % 200;


File: libc.info,  Node: rawclock,  Next: _rdtsc,  Prev: random,  Up: Alphabetical List

rawclock
========

Syntax
------

     #include <time.h>

     unsigned long rawclock(void);

Description
-----------

Returns the number of clock tics (18.2 per second) since midnight.

Return Value
------------

The number of tics.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     /* wait 1/4 second */
     int i = rawclock()+5;
     while (rawclock()<i);


File: libc.info,  Node: _rdtsc,  Next: read,  Prev: rawclock,  Up: Alphabetical List

_rdtsc
======

Syntax
------

     #include <time.h>

     unsigned long long _rdtsc(void);

Description
-----------

This function invokes the hardware instruction `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 `uclock' (*note uclock::).

Return Value
------------

The number of processor cycles.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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;
     }


File: libc.info,  Node: read,  Next: _read,  Prev: _rdtsc,  Up: Alphabetical List

read
====

Syntax
------

     #include <unistd.h>

     ssize_t read(int fd, void *buffer, size_t length);

Description
-----------

This function reads at most LENGTH bytes from file FD into 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,
`read' will read exactly zero bytes.

Directories cannot be read using `read' -- use `readdir' instead.

Return Value
------------

The number of bytes read, zero meaning end-of-file, or -1 for an error.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     char buf[10];
     int r = read(0, buf, 10);


File: libc.info,  Node: _read,  Next: read_child,  Prev: read,  Up: Alphabetical List

_read
=====

Syntax
------

     #include <io.h>

     ssize_t _read(int fildes, void *buf, size_t nbyte);

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 *Note File System
Extensions::. If you don't want this, you should use *Note _dos_read::.

Return Value
------------

The number of bytes read.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: read_child,  Next: read_sel_addr,  Prev: _read,  Up: Alphabetical List

read_child
==========

Syntax
------

     #include <debug/dbgcom.h>

     int read_child (unsigned child_addr, void *buf, unsigned len);

Description
-----------

This function reads the memory of the debugged process starting at
address CHILD_ADDR for LEN bytes, and copies the data read to the
buffer pointed to by 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).  *Note
write_child::.

Return Value
------------

The function return zero if it has successfully transferred the data,
non-zero otherwise (e.g., if the address in CHILD_ADDR is outside the
limits of the debuggee's code segment.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: read_sel_addr,  Next: readdir,  Prev: read_child,  Up: Alphabetical List

read_sel_addr
=============

Syntax
------

     #include <debug/dbgcom.h>

     int read_sel_addr (unsigned offset, void *buf, unsigned len,
                        unsigned sel);

Description
-----------

This function reads the memory starting at offset OFFSET in selector
SEL for LEN bytes, and copies the data read to the buffer pointed to by
BUF.  *Note write_sel_addr::.

Return Value
------------

The function return zero if it has successfully transferred the data,
non-zero otherwise (e.g., if the address in OFFSET is outside the
limits of the segment whose selector is SEL).

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: readdir,  Next: readlink,  Prev: read_sel_addr,  Up: Alphabetical List

readdir
=======

Syntax
------

     #include <dirent.h>

     struct dirent *readdir(DIR *dir);

Description
-----------

This function reads entries from a directory opened by `opendir' (*note
opendir::).  It returns the information in a static buffer with this
format:

     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 */
     };

Note that some directory entries might be skipped by `readdir',
depending on the bits set in the global variable `__opendir_flags'.
*Note __opendir_flags: opendir.

The possible values of the `d_type' member are:

`DT_REG'
     This is a regular file.

`DT_BLK'
     The file is a block device.

`DT_CHR'
     The file is a character device.

`DT_DIR'
     The file is a directory.

`DT_FIFO'
     This is a pipe (never happens in DJGPP).

`DT_LABEL'
     The file is a volume label.

`DT_LNK'
     The file is a symlink.

`DT_SOCK'
     The file is a socket.

`DT_UNKNOWN'
     The file's type is unknown.  This value is put into the `d_type'
     member if the exact file's type is too expensive to compute.  If
     the `__OPENDIR_NO_D_TYPE' flag is set in the global variable
     `__opendir_flags', _all_ files get marked with `DT_UNKNOWN'.

The macro `DTTOIF' (*note DTTOIF::) can be used to convert the `d_type'
member to the equivalent value of the `st_mode' member of `struct
stat', see *Note stat::.

Return Value
------------

A pointer to a static buffer that is overwritten with each call.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)

Notes:

  1. The `__opendir_flags' variable is DJGPP-specific.  The `d_type'
     member is an extension available on some systems such as GNU/Linux.

Example
-------

     DIR *d = opendir(".");
     struct dirent *de;
     while (de = readdir(d))
       puts(de->d_name);
     closedir(d);


File: libc.info,  Node: readlink,  Next: readv,  Prev: readdir,  Up: Alphabetical List

readlink
========

Syntax
------

     #include <unistd.h>

     int readlink(const char *filename, char *buffer, size_t size);

Description
-----------

MSDOS doesn't support symbolic links but DJGPP emulates them.  This
function checks if FILENAME is a DJGPP symlink and the file name that
the links points to is copied into buffer, up to maximum SIZE
characters.  Portable applications should not assume that BUFFER is
terminated with `'\0''.

Return Value
------------

Number of copied characters; value -1 is returned in case of error and
`errno' is set.  When value returned is equal to SIZE, you cannot
determine if there was enough room to copy whole name.  So increase
SIZE and try again.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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.");


File: libc.info,  Node: readv,  Next: realloc,  Prev: readlink,  Up: Alphabetical List

readv
=====

Syntax
------

     #include <sys/uio.h>

     ssize_t readv(int fd, const struct iovec *iov, int iovcnt);

Description
-----------

`readv' performs a scatter-gather read from the specified file
descriptor FD.  The data is written into a group of buffers described
by the array IOV with IOVCNT entries in a similar way to `read' (*note
read: (libc)read.).

`struct iovec' is defined as follows:

     struct iovec {
       void   *iov_base; /* Base address of a memory region for I/O */
       size_t  iov_len;  /* Size of memory region                   */
     };

Return Value
------------

On successful completion the function returns the number of bytes read.
Otherwise, a value of -1 is returned and `errno' is set appropriately.

`EINVAL'
     One of the following conditions is true:

        * The total length to read could overflow a `ssize_t'.

        * IOVCNT was negative, zero or larger than `IOV_MAX'.


Portability
-----------

ANSI/ISO C   No
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992


File: libc.info,  Node: realloc,  Next: realpath,  Prev: readv,  Up: Alphabetical List

realloc
=======

Syntax
------

     #include <stdlib.h>

     void *realloc(void *ptr, size_t size);

Description
-----------

This function changes the size of the region pointed to by 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 `NULL', in which case this
function acts just like `malloc' (*note malloc::).

An application that wants to be robust in the face of a possible
failure of `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 `realloc' returns `NULL'.  See the example below for details.

Note: excessively large requests are rejected.  At present excessively
large means over `INT_MAX' - 65536.

Return Value
------------

On success, a pointer is returned to the memory you should now refer
to.  On failure, `NULL' is returned and the memory pointed to by PTR
prior to the call is not freed.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

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;
       }
     }


File: libc.info,  Node: realpath,  Next: redir_cmdline_delete,  Prev: realloc,  Up: Alphabetical List

realpath
========

Syntax
------

     #include <stdlib.h>

     char *realpath(const char *in_path, char *out_path);

Description
-----------

This function canonicalizes the input path IN_PATH and stores the
result in the buffer pointed to by 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 OUT_PATH, but long filenames are left intact.  *Note
_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
OUT_PATH.  Use of ANSI-standard constant `FILENAME_MAX' (defined on
`stdio.h') or Posix-standard constant `PATH_MAX' (defined on
`limits.h') is recommended.

If OUT_PATH is specified as `NULL', then `realpath' uses `malloc'
(*note malloc::) to allocate a buffer of up to `PATH_MAX' bytes to hold
the resolved path name, and returns a pointer to this buffer.  The
caller should deallocate this buffer using `free' (*note free::).

Return Value
------------

If successful, a pointer to the result buffer is returned. Otherwise,
`NULL' is returned and `errno' is set to indicate which error was
detected.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     char oldpath[100], newpath[PATH_MAX];
     scanf("%s", oldpath);
     realpath(oldpath, newpath);
     printf("that really is %s\n", newpath);


File: libc.info,  Node: redir_cmdline_delete,  Next: redir_cmdline_parse,  Prev: realpath,  Up: Alphabetical List

redir_cmdline_delete
====================

Syntax
------

     #include <debug/redir.h>

     void redir_cmdline_delete (cmdline_t *cmd);

Description
-----------

For the rationale and general description of the debugger redirection
issue, see *Note redir_debug_init::.

This function serves as a destructor for a `cmdline_t' object.  It
frees storage used for the command-line arguments associated with 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 CMD might be a `NULL' pointer, or
if some of members of the `cmdline_t' structure are `NULL' pointers.
*Note redir_debug_init::, for detailed description of the `cmdline_t'
structure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

      redir_cmdline_delete (&child_cmd);


File: libc.info,  Node: redir_cmdline_parse,  Next: redir_debug_init,  Prev: redir_cmdline_delete,  Up: Alphabetical List

redir_cmdline_parse
===================

Syntax
------

     #include <debug/redir.h>

     int  redir_cmdline_parse (const char *args, cmdline_t *cmd);

Description
-----------

For the rationale and general description of the debugger redirection
issue, see *Note redir_debug_init::.

This function parses a command-line tail (i.e., without the program to
be invoked) passed as a string in ARGS.  For every redirection
directive in ARGS, like `>> foo', it opens the file that is the target
of the redirection, and records in CMD the information about these
redirections.  (*Note redir_debug_init::, for details of the
`cmdline_t' structure that is used to hold this information.)  The
command line with redirections removed is placed into `cmd->command'
(typically, it will be used to call `v2loadimage', *note
v2loadimage::), while the rest of information is used by
`redir_to_child' and `redir_to_debugger' to redirect standard handles
before and after calling `run_child'.

Return Value
------------

The function returns zero in case of success, -1 otherwise.  Failure
usually means some kind of syntax error, like `>' without a file name
following it; or a file name that isn't allowed by the underlying OS,
like `lost+found' on DOS.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);
         }


File: libc.info,  Node: redir_debug_init,  Next: redir_to_child,  Prev: redir_cmdline_parse,  Up: Alphabetical List

redir_debug_init
================

Syntax
------

     #include <debug/redir.h>

     int redir_debug_init (cmdline_t *cmd);

Description
-----------

This function initializes the data structure in the CMD variable
required to save and restore debugger's standard handles across
invocations of `run_child' (*note run_child::).  The debugger will then
typically call `redir_to_child' and `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 "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 "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
`open', `_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
`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 `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 `cmdline_t' structure is declared in the header `debug/redir.h' as
follows:

     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;

In the `cmdline_t' structure, the `redirection' member points to an
array of 3 `dbg_redirect' structures, one each for each one of the 3
standard handles.  The `inf_handle' and `our_handle' members of those
structures are used to save the handle used, respectively, by the
debuggee (a.k.a. "the inferior process") and by the debugger.

The CMD variable is supposed to be defined by the debugger's
application code.  `redir_debug_init' is called to initialize that
variable.  It calls `redir_cmdline_delete' to close any open handles
held in CMD and to free any allocated storage; then it fills CMD with
the trivial information (i.e., every standard stream is connected to
the usual handles 0, 1, and 2).

Return Value
------------

`redir_debug_init' returns zero in case of success, or -1 otherwise.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

      if (redir_debug_init (&child_cmd) == -1)
        fatal ("Cannot allocate redirection storage: not enough memory.\n");


File: libc.info,  Node: redir_to_child,  Next: redir_to_debugger,  Prev: redir_debug_init,  Up: Alphabetical List

redir_to_child
==============

Syntax
------

     #include <debug/redir.h>

     int redir_to_child (cmdline_t *cmd);

Description
-----------

For the rationale and general description of the debugger redirection
issue, see *Note 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 `prog > foo', or because the child
program itself redirected one of its standard handles e.g. with a call
to `dup2'.

`redir_to_child' uses information stored in the `cmdline_t' variable
pointed to by the CMD argument to redirect the standard streams as
appropriate for the debuggee, while saving the original debugger's
handles to be restored by `redir_to_debugger'.

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.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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));
         }


File: libc.info,  Node: redir_to_debugger,  Next: regcomp,  Prev: redir_to_child,  Up: Alphabetical List

redir_to_debugger
=================

Syntax
------

     #include <debug/redir.h>

     int redir_to_debugger (cmdline_t *cmd);

Description
-----------

For the rationale and general description of the debugger redirection
issue, see *Note 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 `prog > foo', or because the child program itself
redirected one of its standard handles e.g. with a call to `dup2'.

`redir_to_debugger' uses information stored in the `cmdline_t' variable
pointed to by the CMD argument to redirect the standard streams as
appropriate for the debugger, while saving the original debuggee's
handles to be restored by `redir_to_child'.

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.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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));


File: libc.info,  Node: regcomp,  Next: regerror,  Prev: redir_to_debugger,  Up: Alphabetical List

regcomp
=======

Syntax
------

     #include <sys/types.h>
     #include <regex.h>

     int regcomp(regex_t *preg, const char *pattern, int cflags);

Description
-----------

This function is part of the implementation of POSIX 1003.2 regular
expressions ("RE"s).

`regcomp' compiles the regular expression contained in the PATTERN
string, subject to the flags in CFLAGS, and places the results in the
`regex_t' structure pointed to by PREG.  (The regular expression
syntax, as defined by POSIX 1003.2, is described below.)

The parameter CFLAGS is the bitwise OR of zero or more of the following
flags:

`REG_EXTENDED'
     Compile modern ("extended") REs, rather than the obsolete
     ("basic") REs that are the default.

`REG_BASIC'
     This is a synonym for 0, provided as a counterpart to
     `REG_EXTENDED' to improve readability.  This is an extension,
     compatible with but not specified by POSIX 1003.2, and should be
     used with caution in software intended to be portable to other
     systems.

`REG_NOSPEC'
     Compile with recognition of all special characters turned off.  All
     characters are thus considered ordinary, so the RE in PATTERN is a
     literal string.  This is an extension, compatible with but not
     specified by POSIX 1003.2, and should be used with caution in
     software intended to be portable to other systems.  `REG_EXTENDED'
     and `REG_NOSPEC' may not be used in the same call to `regcomp'.

`REG_ICASE'
     Compile for matching that ignores upper/lower case distinctions.
     See the description of regular expressions below for details of
     case-independent matching.

`REG_NOSUB'
     Compile for matching that need only report success or failure, not
     what was matched.

`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, `[^' bracket expressions and `.'
     never match newline, a `^' anchor matches the null string after any
     newline in the string in addition to its normal function, and the
     `$' anchor matches the null string before any newline in the string
     in addition to its normal function.

`REG_PEND'
     The regular expression ends, not at the first NUL, but just before
     the character pointed to by the `re_endp' member of the structure
     pointed to by PREG.  The `re_endp' member is of type `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 POSIX 1003.2, and should be used with
     caution in software intended to be portable to other systems.


When successful, `regcomp' returns 0 and fills in the structure pointed
to by PREG.  One member of that structure (other than `re_endp') is
publicized: `re_nsub', of type `size_t', contains the number of
parenthesized subexpressions within the RE (except that the value of
this member is undefined if the `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.

Return Value
------------

If `regcomp' succeeds, it returns zero; if it fails, it returns a
non-zero error code, which is one of these:

`REG_BADPAT'
     invalid regular expression

`REG_ECOLLATE'
     invalid collating element

`REG_ECTYPE'
     invalid character class

`REG_EESCAPE'
     `\' applied to unescapable character

`REG_ESUBREG'
     invalid backreference number (e.g., larger than the number of
     parenthesized subexpressions in the RE)

`REG_EBRACK'
     brackets [ ] not balanced

`REG_EPAREN'
     parentheses ( ) not balanced

`REG_EBRACE'
     braces { } not balanced

`REG_BADBR'
     invalid repetition count(s) in { }

`REG_ERANGE'
     invalid character range in [ ]

`REG_ESPACE'
     ran out of memory (an RE like, say,
     `((((a{1,100}){1,100}){1,100}){1,100}){1,100}'' will eventually
     run almost any existing machine out of swap space)

`REG_BADRPT'
     ?, *, or + operand invalid

`REG_EMPTY'
     empty (sub)expression

`REG_ASSERT'
     "can't happen" (you found a bug in `regcomp')

`REG_INVARG'
     invalid argument (e.g. a negative-length string)


Regular Expressions' Syntax
---------------------------

Regular expressions ("RE"s), as defined in POSIX 1003.2, come in two
forms: modern REs (roughly those of `egrep'; 1003.2 calls these
_extended_ REs) and obsolete REs (roughly those of `ed'; 1003.2 _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(*) _branches_, separated by
`|'.  It matches anything that matches one of the branches.

A branch is one(*) or more _pieces_, concatenated.  It matches a match
for the first, followed by a match for the second, etc.

A piece is an _atom_ possibly followed by a single(*) `*', `+', `?', or
_bound_.  An atom followed by `*' matches a sequence of 0 or more
matches of the atom.  An atom followed by `+' matches a sequence of 1
or more matches of the atom.  An atom followed by `?' matches a
sequence of 0 or 1 matches of the atom.

A _bound_ is `{' followed by an unsigned decimal integer, possibly
followed by `,' possibly followed by another unsigned decimal integer,
always followed by `}'.  The integers must lie between 0 and
`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 `i' and no comma matches a sequence of exactly
`i' matches of the atom.  An atom followed by a bound containing one
integer `i' and a comma matches a sequence of `i' or more matches of
the atom.  An atom followed by a bound containing two integers `i' and
`j' matches a sequence of `i' through `j' (inclusive) matches of the
atom.

An atom is a regular expression enclosed in `()' (matching a match for
the regular expression), an empty set of `()' (matching the null
string(*)), a _bracket expression_ (see below), `.' (matching any
single character), `^' (matching the null string at the beginning of a
line), `$' (matching the null string at the end of a line), a `\'
followed by one of the characters `^.[$()|*+?{\\' (matching that
character taken as an ordinary character), a `\' followed by any other
character(*) (matching that character taken as an ordinary character,
as if the `\' had not been present(*)), or a single character with no
other significance (matching that character).  A `{' 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 `\'.

A _bracket expression_ is a list of characters enclosed in `[]'.  It
normally matches any single character from the list (but see below).
If the list begins with `^', it matches any single character (but see
below) _not_ from the rest of the list.  If two characters in the list
are separated by `-', this is shorthand for the full _range_ of
characters between those two (inclusive) in the collating sequence,
e.g. `[0-9]' in ASCII matches any decimal digit.  It is illegal(*) for
two ranges to share an endpoint, e.g. `a-c-e'.  Ranges are very
collating-sequence-dependent, and portable programs should avoid
relying on them.

To include a literal `]' in the list, make it the first character
(following a possible `^').  To include a literal `-', make it the
first or last character, or the second endpoint of a range.  To use a
literal `-' as the first endpoint of a range, enclose it in `[.' and
`.]' to make it a collating element (see below).  With the exception of
these and some combinations using `[' (see next paragraphs), all other
special characters, including `\', 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 `[.' and `.]'
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 `ch' collating element, then the RE `[[.ch.]]*c' matches the
first five characters of "chchcc".

Within a bracket expression, a collating element enclosed in `[=' and
`=]' 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 `[.' and `.]'.)  For example, if
`o' and `^' are the members of an equivalence class, then `[[=o=]]',
`[[=^=]]', and `[o^]' are all synonymous.  An equivalence class may
_not_ be an endpoint of a range.

Within a bracket expression, the name of a _character class_ enclosed
in `[:' and `:]' stands for the list of all characters belonging to
that class.  Standard character class names are:

     alnum	digit	punct
     alpha	graph	space
     blank	lower	upper
     cntrl	print	xdigit

These stand for the character classes defined by `isalnum' (*note
isalnum::), `isdigit' (*note isdigit::), `ispunct' (*note ispunct::),
`isalpha' (*note isalpha::), `isgraph' (*note isgraph::), `isspace'
(*note isspace::) (`blank' is the same as `space'), `islower' (*note
islower::), `isupper' (*note isupper::), `iscntrl' (*note iscntrl::),
`isprint' (*note isprint::), and `isxdigit' (*note 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 `[[:<:]]' and `[[:>:]]' 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 `alnum' character (as defined
by `isalnum' library function) or an underscore.  This is an extension,
compatible with but not specified by 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,
`bb*' matches the three middle characters of "abbbc",
`(wee|week)(knights|nights)' matches all ten characters of
"weeknights", when `(.*).*' is matched against "abc" the parenthesized
subexpression matches all three characters, and when `(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. `x' becomes `[xX]'.  When it
appears inside a bracket expression, all case counterparts of it are
added to the bracket expression, so that (e.g.) `[x]' becomes `[xX]'
and `[^x]' becomes `[^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
POSIX-compliant.

Obsolete (_basic_) regular expressions differ in several respects.
`|', `+', and `?' are ordinary characters and there is no equivalent
for their functionality.  The delimiters for bounds are `\{' and `\}',
with `{' and `}' by themselves ordinary characters.  The parentheses
for nested subexpressions are `\(' and `\)', with `(' and `)' by
themselves ordinary characters.  `^' is an ordinary character except at
the beginning of the RE or(*) the beginning of a parenthesized
subexpression, `$' is an ordinary character except at the end of the RE
or(*) the end of a parenthesized subexpression, and `*' is an ordinary
character if it appears at the beginning of the RE or the beginning of
a parenthesized subexpression (after a possible leading `^').  Finally,
there is one new type of atom, a _back reference_: `\' followed by a
non-zero decimal digit _d_ matches the same sequence of characters
matched by the _d_th parenthesized subexpression (numbering
subexpressions by the positions of their opening parentheses, left to
right), so that (e.g.)  `\([bc]\)\1' matches "bb" or "cc" but not "bc".

History
-------

This implementation of the POSIX regexp functionality was written by
Henry Spencer <henry@zoo.toronto.edu>.

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.

`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, `((((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 `a)b' are legal REs because `)'
is a special character only in the presence of a previous unmatched
`('.  This can't be fixed until the spec is fixed.

The standard's definition of back references is vague.  For example,
does `a\e(\e(b\e)*\e2\e)*d' match "abbbd"?  Until the standard is
clarified, behavior in such cases should not be relied on.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: regerror,  Next: regexec,  Prev: regcomp,  Up: Alphabetical List

regerror
========

Syntax
------


     #include <sys/types.h>
     #include <regex.h>

     size_t regerror(int errcode, const regex_t *preg,
                     char *errbuf, size_t errbuf_size);

Description
-----------

`regerror' maps a non-zero value of ERRCODE from either `regcomp'
(Return Value, *note regcomp::) or `regexec' (Return Value, *note
regexec::) to a human-readable, printable message.

If PREG is non-`NULL', the error code should have arisen from use of
the variable of the type `regex_t' pointed to by PREG, and if the error
code came from `regcomp', it should have been the result from the most
recent `regcomp' using that `regex_t' variable.  (`regerror' may be
able to supply a more detailed message using information from the
`regex_t' than from ERRCODE alone.)  `regerror' places the
`NUL'-terminated message into the buffer pointed to by ERRBUF, limiting
the length (including the `NUL') to at most ERRBUF_SIZE bytes.  If the
whole message won't fit, as much of it as will fit before the
terminating `NUL' is supplied.  In any case, the returned value is the
size of buffer needed to hold the whole message (including terminating
`NUL').  If ERRBUF_SIZE is 0, ERRBUF is ignored but the return value is
still correct.

If the ERRCODE given to `regerror' is first ORed with `REG_ITOA', the
"message" that results is the printable name of the error code, e.g.
"REG_NOMATCH", rather than an explanation thereof.  If ERRCODE is
`REG_ATOI', then PREG shall be non-NULL and the `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 ERRBUF is the
decimal representation of the numeric value of the error code (0 if the
name is not recognized).  `REG_ITOA' and `REG_ATOI' are intended
primarily as debugging facilities; they are extensions, compatible with
but not specified by 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.

Return Value
------------

The size of buffer needed to hold the message (including terminating
`NUL') is always returned, even if ERRBUF_SIZE is zero.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: regexec,  Next: regfree,  Prev: regerror,  Up: Alphabetical List

regexec
=======

Syntax
------

     #include <sys/types.h>
     #include <regex.h>

     int regexec(const regex_t *preg, const char *string,
                 size_t nmatch, regmatch_t pmatch[], int eflags);

Description
-----------

`regexec' matches the compiled RE pointed to by PREG against the
STRING, subject to the flags in EFLAGS, and reports results using
NMATCH, PMATCH, and the returned value.  The RE must have been compiled
by a previous invocation of `regcomp' (*note regcomp::).  The compiled
form is not altered during execution of `regexec', so a single compiled
RE can be used simultaneously by multiple threads.

By default, the NUL-terminated string pointed to by 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 EFLAGS argument is the bitwise OR of zero or more of the following
flags:

`REG_NOTBOL'
     The first character of the string is not the beginning of a line,
     so the `^' anchor should not match before it.  This does not
     affect the behavior of newlines under `REG_NEWLINE' (REG_NEWLINE,
     *note regcomp::).

`REG_NOTEOL'
     The NUL terminating the string does not end a line, so the `$'
     anchor should not match before it.  This does not affect the
     behavior of newlines under `REG_NEWLINE' (REG_NEWLINE, *note
     regcomp::).

`REG_STARTEND'
     The string is considered to start at `STRING + PMATCH[0].rm_so'
     and to have a terminating `NUL' located at
     `STRING + PMATCH[0].rm_eo' (there need not actually be a `NUL' at
     that location), regardless of the value of NMATCH.  See below for
     the definition of PMATCH and NMATCH.  This is an extension,
     compatible with but not specified by POSIX 1003.2, and should be
     used with caution in software intended to be portable to other
     systems.  Note that a non-zero `rm_so' does not imply
     `REG_NOTBOL'; `REG_STARTEND' affects only the location of the
     string, not how it is matched.

`REG_TRACE'
     trace execution (printed to stdout)

`REG_LARGE'
     force large representation

`REG_BACKR'
     force use of backref code


Regular Expressions' Syntax, *Note regcomp::, for a discussion of what
is matched in situations where an RE or a portion thereof could match
any of several substrings of STRING.

If `REG_NOSUB' was specified in the compilation of the RE (REG_NOSUB,
*note regcomp::), or if NMATCH is 0, `regexec' ignores the PMATCH
argument (but see below for the case where `REG_STARTEND' is
specified).  Otherwise, PMATCH should point to an array of NMATCH
structures of type `regmatch_t'.  Such a structure has at least the
members `rm_so' and `rm_eo', both of type `regoff_t' (a signed
arithmetic type at least as large as an `off_t' and a `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 STRING
argument given to `regexec'.  An empty substring is denoted by equal
offsets, both indicating the character following the empty substring.

When `regexec' returns, the 0th member of the PMATCH array is filled in
to indicate what substring of STRING was matched by the entire RE.
Remaining members report what substring was matched by parenthesized
subexpressions within the RE; member `i' reports subexpression `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, `i > preg->re_nsub')--have both `rm_so' and `rm_eo' set to
`-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 `(b*)+' matches "bbb", the parenthesized
subexpression matches the three `b's and then an infinite number of
empty strings following the last `b', so the reported substring is one
of the empties.)

If `REG_STARTEND' is specified in EFLAGS, PMATCH must point to at least
one `regmatch_t' variable (even if NMATCH is 0 or `REG_NOSUB' was
specified in the compilation of the RE, REG_NOSUB, *note regcomp::), to
hold the input offsets for `REG_STARTEND'.  Use for output is still
entirely controlled by NMATCH; if NMATCH is 0 or `REG_NOSUB' was
specified, the value of `pmatch[0]' will not be changed by a successful
`regexec'.

Return Value
------------

Normally, `regexec' returns 0 for success and the non-zero 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:

`REG_ESPACE'
     ran out of memory

`REG_BADPAT'
     the passed argument PREG doesn't point to an RE compiled by
     `regcomp'

`REG_INVARG'
     invalid argument(s) (e.g., `STRING + PMATCH[0].rm_eo' is less than
     `STRING + PMATCH[0].rm_so')


History
-------

This implementation of the POSIX regexp functionality was written by
Henry Spencer <henry@zoo.toronto.edu>.

Bugs
----

`regexec' performance is poor.  NMATCH exceeding 0 is expensive; NMATCH
exceeding 1 is worse.  `regexec' is largely insensitive to RE
complexity _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.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: regfree,  Next: remove,  Prev: regexec,  Up: Alphabetical List

regfree
=======

Syntax
------


     #include <sys/types.h>
     #include <regex.h>

     void regfree(regex_t *preg);

Description
-----------

`regfree' frees any dynamically-allocated storage associated with the
compiled RE pointed to by PREG.  The remaining `regex_t' is no longer a
valid compiled RE and the effect of supplying it to `regexec' or
`regerror' is undefined.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: remove,  Next: remque,  Prev: regfree,  Up: Alphabetical List

remove
======

Syntax
------

     #include <stdio.h>

     int remove(const char *file);

Description
-----------

This function removes the named FILE from the file system.  Unless you
have an un-erase program, the file and its contents are gone for good.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     remove("/tmp/data.tmp");


File: libc.info,  Node: remque,  Next: _rename,  Prev: remove,  Up: Alphabetical List

remque
======

Syntax
------

     #include <search.h>

     void remque(struct qelem *elem);

Description
-----------

This function manipulates queues built from doubly linked lists.  Each
element in the queue must be in the form of `struct qelem' which is
defined thus:

     struct qelem {
       struct qelem *q_forw;
       struct qelem *q_back;
       char q_data[0];
     }

This function removes the entry ELEM from a queue.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _rename,  Next: rename,  Prev: remque,  Up: Alphabetical List

_rename
=======

Syntax
------

     #include <stdio.h>

     int _rename(const char *oldname, const char *newname);

Description
-----------

This function renames an existing file or directory OLDNAME to NEWNAME.
It is much smaller that `rename' (*note 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:

     _rename("c:/path1/mydir", "c:/path1/yourdir");
     _rename("c:/path1/mydir", "c:/path2");

On systems that support long filenames (*note _use_lfn::), `_rename'
can also move directories (so that both calls in the above example
succeed there), unless the `LFN' environment variable is set to `n', or
the `_CRT0_FLAG_NO_LFN' is set in the `_crt0_startup_flags' variable,
*Note _crt0_startup_flags::.

If you don't need the extra functionality offered by `rename' (which
usually is only expected by Unix-born programs), you can use `_rename'
instead and thus make your program a lot smaller.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: rename,  Next: rewind,  Prev: _rename,  Up: Alphabetical List

rename
======

Syntax
------

     #include <stdio.h>

     int rename(const char *oldname, const char *newname);

Description
-----------

This function renames an existing file or directory OLDNAME to NEWNAME.
If NEWNAME exists, then it is first removed.  If NEWNAME is a
directory, it must be empty (or else `errno' will be set to
`ENOTEMPTY'), and must not include OLDNAME in its path prefix
(otherwise, `errno' will be set to `EINVAL').  If NEWNAME exists, both
OLDNAME and NEWNAME must be of the same type (both directories or both
regular files) (or else `errno' will be set to `ENOTDIR' or `EISDIR'),
and must reside on the same logical device (otherwise, `errno' will be
set to `EXDEV').  Wildcards are not allowed in either OLDNAME or
NEWNAME.  DOS won't allow renaming a current directory even on a
non-default drive (you will get the `EBUSY' or `EINVAL' in `errno').
`ENAMETOOLONG' will be returned for pathnames which are longer than the
limit imposed by DOS.  If OLDNAME doesn't exist, `errno' will be set to
`ENOENT'.  For most of the other calamities, DOS will usually set
`errno' to `EACCES'.

If anything goes wrong during the operation of `rename()', the function
tries very hard to leave the things as ther were before it was invoked,
but it might not always succeed.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     rename("c:/mydir/some.doc", "c:/yourdir/some.sav");
     rename("c:/path1/mydir", "c:/path2");


File: libc.info,  Node: rewind,  Next: rewinddir,  Prev: rename,  Up: Alphabetical List

rewind
======

Syntax
------

     #include <stdio.h>

     void rewind(FILE *file);

Description
-----------

This function repositions the file pointer to the beginning of the file
and clears the error indicator.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     rewind(stdin);


File: libc.info,  Node: rewinddir,  Next: rindex,  Prev: rewind,  Up: Alphabetical List

rewinddir
=========

Syntax
------

     #include <dirent.h>

     void rewinddir(DIR *dir);

Description
-----------

This function resets the position of the DIR so that the next call to
`readdir' (*note readdir::) starts at the beginning again.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     DIR *d = opendir(".");
     rewinddir(d);


File: libc.info,  Node: rindex,  Next: rmdir,  Prev: rewinddir,  Up: Alphabetical List

rindex
======

Syntax
------

     #include <strings.h>

     char *rindex(const char *string, int ch);

Description
-----------

Returns a pointer to the last occurrence of CH in STRING.  Note that
the `NULL' character counts, so if you pass zero as CH you'll get a
pointer to the end of the string back.

Return Value
------------

A pointer to the character, or `NULL' if it wasn't found.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     char *last_slash = rindex(filename, '/');


File: libc.info,  Node: rmdir,  Next: run_child,  Prev: rindex,  Up: Alphabetical List

rmdir
=====

Syntax
------

     #include <unistd.h>

     int rmdir(const char *dirname);

Description
-----------

This function removes directory DIRNAME.  The directory must be empty.

Return Value
------------

Zero if the directory was removed, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     rmdir("/tmp/datadir");


File: libc.info,  Node: run_child,  Next: save_npx,  Prev: rmdir,  Up: Alphabetical List

run_child
=========

Syntax
------

     #include <debug/dbgcom.h>

     void run_child (void);

Description
-----------

This function starts or resumes the debugged program, via a `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 `longjmp' back to `run_child', and it will
then return to the caller.

After `run_child' returns, the debugger usually examines the `a_tss'
variable to find out the reason the debuggee stopped.  The `a_tss'
variable is defined by the header `debug/tss.h' as follows:

     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;

See the example below for a typical tests after `run_child' returns.

Note that, generally, you'd need to save the standard handles before
calling `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.  *Note
redir_to_child::, and see *Note redir_to_debugger::.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 */
       }


File: libc.info,  Node: save_npx,  Next: sbrk,  Prev: run_child,  Up: Alphabetical List

save_npx
========

Syntax
------

     #include <debug/dbgcom.h>

     extern NPX npx;
     void save_npx (void);

Description
-----------

This function saves the state of the x87 numeric processor in the
external variable `npx'.  This variable is a structure defined as
follows in the header `debug/dbgcom.h':

     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;

`save_npx' should be called immediately before `run_child' (*note
run_child::) is called to begin or resume the debugged program.

To restore the x87 state when control is returned to the debugger, call
`load_npx', see *Note load_npx::.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

      save_npx ();
      run_child ();
      load_npx ();


File: libc.info,  Node: sbrk,  Next: scanf,  Prev: save_npx,  Up: Alphabetical List

sbrk
====

Syntax
------

     #include <unistd.h>

     void *sbrk(int delta)

Description
-----------

This function changes the "break" of the program by adding 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 `malloc' gets memory from) by increasing the
break.

This function is normally accessed only by `malloc' (*note malloc::).

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.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     char *buf;
     buf = sbrk(1000); /* allocate space */


File: libc.info,  Node: scanf,  Next: SCN,  Prev: sbrk,  Up: Alphabetical List

scanf
=====

Syntax
------

     #include <stdio.h>

     int scanf(const char *format, ...);

Description
-----------

This function scans formatted text from `stdin' and stores it in the
variables pointed to by the arguments.  *Note 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 `c' and `['
also skip leading whitespace automatically.  Conversions can be applied
to the Nth argument after the format in the argument list, rather than
to the next unused argument.  In this case, the conversion specifier
character `%' is replaced by the sequence `%N$', where N is a decimal
integer in the range [`1', `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 `%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, `%' or
`%N$' -- but the two forms cannot be mixed within a single format
string.  The only exception to this is that `%%' or `%*' can be mixed
with the `%N$' form.  When numbered argument specifications are used,
specifying the Nth argument requires that all the leading arguments,
from the first to the (N-1)th, are pointers.  Each conversion specifier
contains the following fields:

   * An asterisk (`*') 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.

   * A width specifier, which specifies the maximum number of input
     characters to use in the conversion.

   * A `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, `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
     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 GNU extension.

   * An optional conversion qualifier, which may be:

    `hh'
          to specify `char';

    `h'
          to specify `short' integers;

    `j'
          to specify `intmax_t' or `uintmax_t' integers;

    `l'
          to specify doubles or `long' integers;

    `ll'
          (two lower-case ell letters) to specify `long long' integers;
          to specify `long' doubles, although this is non-standard;

    `L'
          to specify `long' doubles;

    `t'
          to specify `ptrdiff_t';

    `z'
          to specify `size_t'.

     If the `h' qualifier appears before a specifier that implies
     conversion to a `long' or `float' or `double', like in `%hD' or
     `%hf', it is generally ignored.

   * The conversion type specifier(1):

    `c'
          Copy the next character (or WIDTH characters) to the given
          buffer.  This conversion suppresses skipping of the leading
          whitespace; use `%1s' to read the next non-whitespace
          character.  Unlike with `%s', the copied characters are *not*
          terminated with a null character.  If the WIDTH parameter is
          not specified, a WIDTH of one is implied.

    `d'
          Convert the input to a signed `int' using 10 as the base of
          the number representation.

    `hhd'
          Convert the input to a signed `char' using 10 as the base.

    `hd'
          Convert the input to a signed `short' using 10 as the base.

    `jd'
          Convert the input to an `intmax_t' using 10 as the base.

    `ld'
    `D'
          Convert the input to a signed `long' using 10 as the base.

    `Ld'
    `lld'
    `lD'
          Convert the input to a signed `long long' using 10 as the
          base.

    `td'
          Convert the input to a `ptrdiff_t' using 10 as the base.

    `zd'
          Convert the input to a `size_t' using 10 as the base.

    `a'
    `A'
          Convert the input of the form [+|-]0xH.HHHHp|P[+|-]DDD to a
          floating point number (a `float').

    `e'
    `E'
    `f'
    `F'
    `g'
    `G'
          Convert the input to a floating point number (a `float').

    `la'
    `lA'
          Convert the input of the form [+|-]0xH.HHHHp|P[+|-]DDD to a
          floating point number (a `double').

    `le'
    `lE'
    `lf'
    `lF'
    `lg'
    `lG'
          Convert the input to a floating point number (a `double').

    `La'
    `LA'

    `lla'
    `llA'
          Convert the input of the form [+|-]0xH.HHHHp|P[+|-]DDD to a
          floating point number (a `double').

    `Le'
    `LE'
    `lle'
    `llE'
    `Lf'
    `LF'
    `llf'
    `llF'
    `Lg'
    `LG'
    `llg'
    `llG'
          Convert the input to a floating point number (a `long double'.

    `i'
          Convert the input, determining base automatically by the
          presence of `0x' or `0' prefixes, and store in a signed `int'.
          *Note strtol::.

    `hhi'
          Like `i', but stores the result in a signed `char'.

    `hi'
          Like `i', but stores the result in a signed `short'.

    `ji'
          Like `i', but stores the result in an `intmax_t'.

    `li'
    `I'
          Like `i', but stores the result in a signed `long'.

    `Li'
    `lli'
    `lI'
          Like `i', but stores the result in a signed `long long'.

    `ti'
          Like `i', but stores the result in a `ptrdiff_t'.

    `zi'
          Like `i', but stores the result in a `size_t'.

    `n'
          Store the number of characters scanned so far into the `int'
          pointed to by the argument.

    `hhn'
          Like `n', but the argument should point to a signed `char'.

    `hn'
          Like `n', but the argument should point to a signed `short'.

    `jn'
          Like `n', but the argument should point to an `intmax_t'.

    `ln'
          Like `n', but the argument should point to a signed `long'.

    `Ln'
    `lln'
          Like `n', but the argument should point to a signed `long
          long'.

    `tn'
          Like `n', but the argument should point to a `ptrdiff_t'.

    `zn'
          Like `n', but the argument should point to a `size_t'.

    `o'
          Convert the input to an unsigned `int', using base 8.

    `hho'
          Convert the input to an unsigned `char', using base 8.

    `ho'
          Convert the input to an unsigned `short', using base 8.

    `jo'
          Convert the input to an `uintmax_t', using base 8.

    `lo'
    `O'
          Convert the input to an unsigned `long', using base 8.

    `Lo'
    `llo'
    `lO'
          Convert the input to an unsigned `long long', using base 8.

    `to'
          Convert the input to a `ptrdiff_t', using base 8.

    `zo'
          Convert the input to a `size_t', using base 8.

    `p'
          Convert the input to a pointer.  This is like using the `x'
          format.

    `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.

    `u'
          Convert the input to an unsigned `int' using 10 as the base.

    `hhu'
          Convert the input to an unsigned `char' using 10 as the base.

    `hu'
          Convert the input to an unsigned `short' using 10 as the base.

    `ju'
          Convert the input to an `uintmax_t' using 10 as the base.

    `lu'
    `U'
          Convert the input to an unsigned `long' using 10 as the base.

    `Lu'
    `llu'
    `lU'
          Convert the input to an unsigned `long long' using 10 as the
          base.

    `tu'
          Convert the input to a `ptrdiff_t' using 10 as the base.

    `zu'
          Convert the input to a `size_t' using 10 as the base.

    `x'
    `X'
          Convert the input to an unsigned `int', using base 16.

    `hhx'
    `hhX'
          Convert the input to an unsigned `char', using base 16.

    `hx'
    `hX'
          Convert the input to an unsigned `short', using base 16.

    `jx'
    `jX'
          Convert the input to an `uintmax_t', using base 16.

    `lx'
    `lX'
          Convert the input to an unsigned `long', using base 16.

    `Lx'
    `LX'
    `llx'
    `llX'
          Convert the input to an unsigned `long long', using base 16.

    `tx'
    `tX'
          Convert the input to a `ptrdiff_t', using base 16.

    `zx'
    `zX'
          Convert the input to a `size_t', using base 16.

    `[...]'
          Stores the matched characters in a `char' array, followed by a
          terminating null character.  If you do not specify the WIDTH
          parameter, `scanf' behaves as if WIDTH had a very large
          value.  Up to 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:
          `[abcd]') or a range of characters (example: `[a-d]').  If
          the first character is a caret (`^'), 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
          (`]'), put it immediately after `[' or `[^'.  To specify a
          literal dash (`-'), write it either immediately after `[' or
          `[^', or immediately before the closing `]'.

    `%'
          This must match a percent character in the input.



Integer formats make use of `strtol' or `strtoul' to perform the actual
conversions.  Floating-point conversions use `strtod' and `_strtold'.

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, `EOF' is returned.  Note that literal characters (including
whitespace) in the format string which matched input characters count
as "converted items", so input failure _after_ such characters were
read and matched will *not* cause `EOF' to be returned.  If the `m'
modifier character has been used and the memory allocation failed, then
ERRNO will be set to `ENOMEM'.

Portability
-----------

ANSI/ISO C   C89; C99 (see note 1); (see note 2)
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 3)

Notes:

  1. The `hh', `j', `t' and `z' length modifiers and the `a', `A' and
     `F' conversion specifiers first appeared in the ANSI C99 standard.

  2. The conversion specifiers `F', `D', `I', `O', and `U' are DJGPP
     extensions; they are provided for compatibility with Borland C and
     other compilers.  The conversion specifiers for the `long long'
     data type are GCC extensions.  The meaning of `[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).

  3. The `m' modifier character is a GNU extension and is specified in
     the upcoming revision of the POSIX.1 standard.


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);

---------- Footnotes ----------

(1) Some of the combinations listed below are non-standard.  If you use
the non-standard specifiers, a compiler could complain.


File: libc.info,  Node: SCN,  Next: Screen Variables,  Prev: scanf,  Up: Alphabetical List

SCN
===

Syntax
------

     #include <inttypes.h>

Description
-----------

The `SCN' family of macros allows integers to be input in a portable
manner using the `scanf' family of functions (*note scanf::).  They
include a conversion qualifier, to specify the width of the type (e.g.:
`l' for `long'), and the conversion type specifier (e.g.: `d' for
decimal display of integers).

The `SCN' family of macros should be used with the types defined in the
header `<stdint.h>'.  For example: `int8_t', `uint_fast32_t',
`uintptr_t', `intmax_t'.

Below N can be 8, 16, 32 or 64.  The `SCN' macros are:

`SCNdN'
`SCNiN'
     The `d' and `i' type conversion specifiers for a type `intN_t' of
     N bits.

`SCNdLEASTN'
`SCNiLEASTN'
     The `d' and `i' type conversion specifiers for a type
     `int_leastN_t' of N bits.

`SCNdFASTN'
`SCNiFASTN'
     The `d' and `i' type conversion specifiers for a type
     `int_fastN_t' of N bits.

`SCNdMAX'
`SCNiMAX'
     The `d' and `i' type conversion specifiers for a type `intmax_t'.

`SCNdPTR'
`SCNiPTR'
     The `d' and `i' type conversion specifier for a type `intptr_t'.

`SCNoN'
`SCNuN'
`SCNxN'
     The `o', `u' and `x' type conversion specifiers for a type
     `uintN_t' of N bits.

`SCNoLEASTN'
`SCNuLEASTN'
`SCNxLEASTN'
     The `o', `u' and `x' type conversion specifiers for a type
     `uint_LEASTN_t' of N bits.

`SCNoFASTN'
`SCNuFASTN'
`SCNxFASTN'
     The `o', `u' and `x' type conversion specifiers for a type
     `uint_FASTN_t' of N bits.

`SCNoMAX'
`SCNuMAX'
`SCNxMAX'
     The `o', `u' and `x' type conversion specifiers for a type
     `uintmax_t'.

`SCNoPTR'
`SCNuPTR'
`SCNxPTR'
     The `o', `u' and `x' type conversion specifiers for a type
     `uintptr_t'.


Return Value
------------

Not applicable.

Portability
-----------

ANSI/ISO C   C99; not C89
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992

Example
-------

     intmax_t m;
     int ret;

     ret = sscanf("0x1000", "%" SCNxMAX, &m);


File: libc.info,  Node: Screen Variables,  Next: ScreenClear,  Prev: SCN,  Up: Alphabetical List

Screen Variables
================

Syntax
------

     #include <go32.h>
     #include <pc.h>

     unsigned long ScreenPrimary;
     unsigned long ScreenSecondary;
     extern unsigned char ScreenAttrib;

Description
-----------

The first two variables (actually, they are #define'd aliases to fields
in the _GO32_INFO_BLOCK structure *note _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 (*Note dosmemget::, *note
dosmemput::) or any one of the far pointer functions (*note _far*::),
as the video memory is _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).

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

_farpokew(_dos_ds, ScreenPrimary, ( ((unsigned short) attr) << 8) +
char ));



File: libc.info,  Node: ScreenClear,  Next: ScreenCols,  Prev: Screen Variables,  Up: Alphabetical List

ScreenClear
===========

Syntax
------

     #include <pc.h>

     void  ScreenClear(void);

Description
-----------

This function clears the text screen.  It overwrites it by blanks with
the current background and foreground as specified by ScreenAttrib
(*note Screen Variables::).

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     ScreenClear();


File: libc.info,  Node: ScreenCols,  Next: ScreenGetChar,  Prev: ScreenClear,  Up: Alphabetical List

ScreenCols
==========

Syntax
------

     #include <pc.h>

     int ScreenCols(void);

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.

Return Value
------------

The number of columns.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------


     int available_columns = ScreenCols();


File: libc.info,  Node: ScreenGetChar,  Next: ScreenGetCursor,  Prev: ScreenCols,  Up: Alphabetical List

ScreenGetChar
=============

Syntax
------

     #include <pc.h>

     void  ScreenGetChar(int *ch, int *attr, int col, int row);

Description
-----------

This function stores the character and attribute of the current primary
screen at row given by ROW and column given by COL (these are
zero-based) into the integers whose address is specified by CH and
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
`NULL' in each of the pointers if you do not want to retrieve the the
corresponding information.

_Warning:_ note that both the variables CH and ATTR are pointers to an
`int', not to a `char'!  You *must* pass a pointer to an `int' there,
or your program will crash or work erratically.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     int ch, attr;

     ScreenGetChar(&ch, &attr, 0, 0);


File: libc.info,  Node: ScreenGetCursor,  Next: ScreenMode,  Prev: ScreenGetChar,  Up: Alphabetical List

ScreenGetCursor
===============

Syntax
------

     #include <pc.h>

     void  ScreenGetCursor(int *row, int *column);

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 ROW and COLUMN.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     ScreenGetCursor(&where_r, &where_c);


File: libc.info,  Node: ScreenMode,  Next: ScreenPutChar,  Prev: ScreenGetCursor,  Up: Alphabetical List

ScreenMode
==========

Syntax
------

     #include <pc.h>

     int  ScreenMode(void);

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.

Return Value
------------

The video mode.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     video_mode = ScreenMode();


File: libc.info,  Node: ScreenPutChar,  Next: ScreenPutString,  Prev: ScreenMode,  Up: Alphabetical List

ScreenPutChar
=============

Syntax
------

     #include <pc.h>

     void  ScreenPutChar(int ch, int attr, int col, int row);

Description
-----------

This function writes the character whose value is specified in CH with
an attribute ATTR at row given by ROW and column given by 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.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     ScreenPutChar('R', (BLUE << 4) | LIGHTMAGENTA, 75, 0);


File: libc.info,  Node: ScreenPutString,  Next: ScreenRetrieve,  Prev: ScreenPutChar,  Up: Alphabetical List

ScreenPutString
===============

Syntax
------

     #include <pc.h>

     void  ScreenPutString(const char *str, int attr, int column, int row);

Description
-----------

Beginning at screen position given by COLUMN and ROW, this function
displays the string given by STR.  Each string character gets the
attribute given by ATTR.  If COLUMN or ROW have values outside legal
range for current video mode, nothing happens.  The variables ROW and
COLUMN are zero-based (e.g., the topmost row is row 0).

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     ScreenPutString("Hello, world!", (BLUE << 4) | LIGHTBLUE, 20, 10);


File: libc.info,  Node: ScreenRetrieve,  Next: ScreenRows,  Prev: ScreenPutString,  Up: Alphabetical List

ScreenRetrieve
==============

Syntax
------

     #include <pc.h>

     void  ScreenRetrieve(void *buf);

Description
-----------

This function stores a replica of the current primary screen contents in
the buffer pointed to by BUF.  It assumes without checking that BUF has
enough storage to hold the data.  The required storage can be computed
as `ScreenRows()*ScreenCols()*2' (*note ScreenRows::, *note
ScreenCols::).

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     unsigned *saved_screen = (unsigned *)alloca(ScreenRows()*ScreenCols()*2;

     ScreenRetrieve(saved_screen);


File: libc.info,  Node: ScreenRows,  Next: ScreenSetCursor,  Prev: ScreenRetrieve,  Up: Alphabetical List

ScreenRows
==========

Syntax
------

     #include <pc.h>

     int ScreenRows(void);

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.

Return Value
------------

The number of rows.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------


     int rows = ScreenRows();


File: libc.info,  Node: ScreenSetCursor,  Next: ScreenUpdate,  Prev: ScreenRows,  Up: Alphabetical List

ScreenSetCursor
===============

Syntax
------

     #include <pc.h>

     void  ScreenSetCursor(int  row, int  column);

Description
-----------

This function moves the cursor position on the default video page to the
point given by (zero-based) ROW and COLUMN, by calling function 2 of
interrupt 10h.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     ScreenSetCursor(0, 0);   /* home the cursor */


File: libc.info,  Node: ScreenUpdate,  Next: ScreenUpdateLine,  Prev: ScreenSetCursor,  Up: Alphabetical List

ScreenUpdate
============

Syntax
------

     #include <pc.h>

     void  ScreenUpdate(void *buf);

Description
-----------

This function writes the contents of the buffer BUF to the primary
screen.  The buffer should contain an exact replica of the video memory,
including the characters and their attributes.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     ScreenUpdate(saved_screen);


File: libc.info,  Node: ScreenUpdateLine,  Next: ScreenVisualBell,  Prev: ScreenUpdate,  Up: Alphabetical List

ScreenUpdateLine
================

Syntax
------

     #include <pc.h>

     void  ScreenUpdateLine(void *buf, int row);

Description
-----------

This function writes the contents of BUF to the screen line number
given in ROW (the topmost line is row 0), on the primary screen.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     ScreenUpdateLine(line_buf, 10);


File: libc.info,  Node: ScreenVisualBell,  Next: searchpath,  Prev: ScreenUpdateLine,  Up: Alphabetical List

ScreenVisualBell
================

Syntax
------

     #include <pc.h>

     void  ScreenVisualBell(void);

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.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     ScreenVisualBell();


File: libc.info,  Node: searchpath,  Next: seekdir,  Prev: ScreenVisualBell,  Up: Alphabetical List

searchpath
==========

Syntax
------

     #include <dir.h>

     char * searchpath(const char *file);

Description
-----------

Given a name of a file in FILE, searches for that file in a list of
directories, including the current working directory and directories
listed in the `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 `open' or `stat').

If FILE includes a drive letter or leading directories, `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 `PATH' in turn.  Note that
this will find e.g. `c:/foo/bar/baz.exe' if you pass `bar/baz.exe' to
`searchpath' and if `c:/foo' is mentioned in `PATH'.

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 `NULL'.  (The static buffer is overwritten on each call.)

Portability
-----------

ANSI/ISO C   No
POSIX        No

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. `c:/foo/bar/baz.exe', even if the directory
`c:/foo/bar' doesn't exist, provided that `baz.exe' is somewhere on
your `PATH'.  We think this is a bug, so DJGPP's implementation doesn't
behave like that.

Example
-------

       printf("%s was found as %s\n", argv[1], searchpath(argv[1]));


File: libc.info,  Node: seekdir,  Next: select,  Prev: searchpath,  Up: Alphabetical List

seekdir
=======

Syntax
------

     #include <dirent.h>

     void seekdir(DIR *dir, long loc);

Description
-----------

This function sets the location pointer in DIR to the specified LOC.
Note that the value used for LOC should be either zero or a value
returned by `telldir' (*note telldir::).  The next call to `readdir'
(*note readdir::) will read whatever entry follows that point in the
directory.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     int q = telldir(dir);
     do_stuff();
     seekdir(dir, q);


File: libc.info,  Node: select,  Next: __set_fd_flags,  Prev: seekdir,  Up: Alphabetical List

select
======

Syntax
------

     #include <time.h>
     #include <string.h>

     int
     select(int nfds,
     	fd_set *readfds,
     	fd_set *writefds,
     	fd_set *exceptfds,
     	struct timeval *timeout)

Description
-----------

This function waits for files to be ready for input or output, or to
have exceptional condition pending, or for a timeout.

Each `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, P is a pointer to
an `fd_set' object and N is a file descriptor):

`FD_ZERO(p)'
     Initialize the set P to all zeros.

`FD_SET(n, p)'
     Set member N in set P.

`FD_CLR(n, p)'
     Clear member N in set P.

`FD_ISSET(n, p)'
     Return the value of member N in set P.

`FD_SETSIZE'
     The maximum number of descriptors supported by the system.


The NFDS parameter is the number of bits to be examined in each of the
`fd_set' sets: the function will only check file descriptors `0'
through `NFDS - 1', even if some bits are set for descriptors beyond
that.

On input, some of the bits of each one of the `fd_set' sets for which
the function should wait, should be set using the `FD_SET' macro.
`select' examines only those descriptors whose bits are set.

Any of `readfds', `writefds', and `exceptfds' can be a `NULL' pointer,
if the caller is not interested in testing the corresponding conditions.

On output, if `select' returns a non-negative value, each non-`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 `select' returns -1, meaning a failure, the
descriptor sets are _unchanged_, so you should always test the return
value before looking at the bits in the returned sets.

The 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 `struct timeval' variable
(timeout: `select' will repeatedly test all the descriptors until some
of them become ready, or the timeout expires).

`struct timeval' is defined as follows:

     struct timeval {
       time_t tv_sec;
       long tv_usec;
     };

Return Value
------------

On successful return, `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 `select'
returns 0 (i.e., the timeout has expired), all the non-`NULL' sets have
all their bits reset to zero.

On failure, `select' returns -1, sets `errno' to a suitable value, and
leaves the descriptor sets unchanged.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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");
         }

Implementation Notes
--------------------

The following notes describe some details pertinent to the DJGPP
implementation of `select':

   * While `select' waits for the timeout to expire, it repeatedly calls
     the `__dpmi_yield' function (*note __dpmi_yield::), so that any
     other programs that run at the same time (e.g., on Windows) get
     more CPU time.

   * A file handle that belongs to a `FILE' object created by `fopen'
     or `fdopen' (*note fopen::) for which `feof' or `ferror' return
     non-zero, will be reported in the `exceptfds' set; also, such a
     handle will be reported not input-ready if there are no pending
     buffered characters in the `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 `select' with buffered I/O.

   * DOS doesn't support exceptional conditions, so file handles used
     for unbuffered I/O will _never_ be marked in `exceptfds'.

   * DOS always returns an output-ready indication for a file descriptor
     connected to a disk file.  So use of `writefds' is only meaningful
     for character devices.

   * 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, `select' will indicate that file handle 0 is ready for
     input, but a call to `getc' will still block until the <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 `getkey' (*note getkey::) or with raw input DOS functions
     such as `getch' (*note getch::), or switch the handle to binary
     mode with a call to `setmode' (*note setmode::).


File: libc.info,  Node: __set_fd_flags,  Next: __set_fd_properties,  Prev: select,  Up: Alphabetical List

__set_fd_flags
==============

Syntax
------

     #include <libc/fd_props.h>

     void __set_fd_flags(int fd, unsigned long flags);

Description
-----------

This internal function adds the combination of flags FLAGS to the flags
associated with the file descriptor FD.  The flags are some properties
that may be associated with a file descriptor (*note
__set_fd_properties::).

The caller should first check that FD has properties associated with
it, by calling `__has_fd_properties' (*note __has_fd_properties::).

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: __set_fd_properties,  Next: _set_screen_lines,  Prev: __set_fd_flags,  Up: Alphabetical List

__set_fd_properties
===================

Syntax
------

     #include <libc/fd_props.h>

     int __set_fd_properties(int fd, const char *filename, int open_flags);

Description
-----------

This is an internal function that stores information about the file
descriptor FD in a `fd_properties' struct.  It is called by `open' and
its helper functions.

The file name stored in `fd_properties' is the result of the
`_truename' function (*note _truename::) on FILENAME.  The OPEN_FLAGS
are scanned and the temporary and append flags are stored in the
`flags' field in `fd_properties'.

     struct fd_properties
     {
       unsigned char ref_count;
       char *filename;
       unsigned long flags;
       fd_properties *prev;
       fd_properties *next;
     };

`flags' can contain a combination of bits:

`FILE_DESC_TEMPORARY'
     Delete `filename' when `ref_count' becomes zero.

`FILE_DESC_ZERO_FILL_EOF_GAP'
     Tell `write' and `_write' to test for file offset greater than
     EOF.  Set by `lseek' and `llseek'.

`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.

`FILE_DESC_PIPE'
     The file descriptor is used in emulating a pipe.

`FILE_DESC_APPEND'
     The file pointer will be set to the end of file before each write.

`FILE_DESC_DIRECTORY'
     The file descriptor is for a directory.


The `flags' can be manipulated using `__set_fd_flags' (*note
__set_fd_flags::), `__clear_fd_flags' (*note __clear_fd_flags::) and
`__get_fd_flags' (*note __get_fd_flags::).

The file name can be retrieved using `__get_fd_name' (*note
__get_fd_name::).

For more information, see `__clear_fd_properties' (*note
__clear_fd_properties::) and `__dup_fd_properties' (*note
__dup_fd_properties::).

Return Value
------------

Returns 0 on success.  Returns -1 when unable to store the information.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _set_screen_lines,  Next: setbuf,  Prev: __set_fd_properties,  Up: Alphabetical List

_set_screen_lines
=================

Syntax
------

     #include <conio.h>

     void _set_screen_lines(int nlines);

Description
-----------

This function sets the text screen width to 80 and its height to the
value given by 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
`gettextinfo()' will return the actual screen dimensions as set by
`_set_screen_lines()'.  That is, you can e.g. test whether
`_set_screen_lines()' succeeded by checking the screen height returned
by `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.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: setbuf,  Next: setbuffer,  Prev: _set_screen_lines,  Up: Alphabetical List

setbuf
======

Syntax
------

     #include <stdio.h>

     void setbuf(FILE *file, char *buffer);

Description
-----------

This function modifies the buffering characteristics of 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 `fopen'.

If the BUFFER passed is `NULL', the file is set to unbuffered.  If a
non-`NULL' buffer is passed, it must be at least `BUFSIZ' bytes in
size, and the file is set to fully buffered.

*Note setbuffer::.  *Note setlinebuf::.  *Note setvbuf::.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     setbuf(stdout, malloc(BUFSIZ));


File: libc.info,  Node: setbuffer,  Next: setcbrk,  Prev: setbuf,  Up: Alphabetical List

setbuffer
=========

Syntax
------

     #include <stdio.h>

     void setbuffer(FILE *file, char *buffer, int length);

Description
-----------

This function modifies the buffering characteristics of 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 `fopen'.

If the BUFFER passed is `NULL', the file is set to unbuffered.  If a
non-`NULL' buffer is passed, it must be at least SIZE bytes in size,
and the file is set to fully buffered.

*Note setbuf::.  *Note setlinebuf::.  *Note setvbuf::.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     setbuffer(stdout, malloc(10000), 10000);


File: libc.info,  Node: setcbrk,  Next: _setcursortype,  Prev: setbuffer,  Up: Alphabetical List

setcbrk
=======

Syntax
------

     #include <dos.h>

     void setcbrk(int check);

Description
-----------

Set the setting of the Ctrl-Break checking flag in MS-DOS.  If CHECK is
zero, checking is not done.  If nonzero, checking is done.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: _setcursortype,  Next: setdate,  Prev: setcbrk,  Up: Alphabetical List

_setcursortype
==============

Syntax
------

     #include <conio.h>

     void _setcursortype(int _type);

Description
-----------

Sets the cursor type.  _TYPE is one of the following:

`_NOCURSOR'
     No cursor is displayed.

`_SOLIDCURSOR'
     A solid block is displayed.

`_NORMALCURSOR'
     An underline cursor is displayed.


Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: setdate,  Next: setdisk,  Prev: _setcursortype,  Up: Alphabetical List

setdate
=======

Syntax
------

     #include <dos.h>

     void setdate(struct date *ptr);

Description
-----------

This function sets the current time.

For the description of `struct date', see *Note getdate::.  Also see
*Note settime::.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     struct date d;
     setdate(&d);


File: libc.info,  Node: setdisk,  Next: setenv,  Prev: setdate,  Up: Alphabetical List

setdisk
=======

Syntax
------

     #include <dir.h>

     int setdisk(int drive);

Description
-----------

This function sets the current disk (0=A).

See also *Note getdisk::.

Return Value
------------

The highest drive actually present that the system can reference.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     printf("There are %d drives\n", setdisk(getdisk()));


File: libc.info,  Node: setenv,  Next: setftime,  Prev: setdisk,  Up: Alphabetical List

setenv
======

Syntax
------

     #include <stdlib.h>

     int setenv(const char *name, const char *value, int rewrite);

Description
-----------

This function sets the environment variable NAME to VALUE.  If 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.

Return Value
------------

Zero on success, -1 on failure; `errno' is set to the reason for
failure: `EINVAL' if the NAME parameter is `NULL' or points to an empty
string, or `ENOMEM' if there was insufficient memory to add the
variable to the environment.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)

Notes:

  1. This function is new to the Posix 1003.1-200x draft.  Our
     implementation allows NAME to contain a `=', while the POSIX spec
     does not; the portion of NAME up to but not including the `=' will
     be used as the name for the environment variable.


File: libc.info,  Node: setftime,  Next: setgid,  Prev: setenv,  Up: Alphabetical List

setftime
========

Syntax
------

     #include <dos.h>

     int setftime(int handle, struct ftime *ftimep);

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.

*Note getftime::, for the description of `struct ftime'.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: setgid,  Next: setgrent,  Prev: setftime,  Up: Alphabetical List

setgid
======

Syntax
------

     #include <unistd.h>

     int setgid(gid_t gid);

Description
-----------

This function is simulated, since MS-DOS does not support group IDs.

Return Value
------------

If GID is equal to that returned by *note getgid::, returns zero.
Otherwise, returns -1 and sets `errno' to EPERM.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: setgrent,  Next: setitimer,  Prev: setgid,  Up: Alphabetical List

setgrent
========

Syntax
------

     #include <grp.h>

     void setgrent(void);

Description
-----------

This function should be called before any call to `getgrent',
`getgrgid', or `getgrnam', to start searching the groups' list from the
beginning.  *Note getgrent::.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: setitimer,  Next: setjmp,  Prev: setgrent,  Up: Alphabetical List

setitimer
=========

Syntax
------

     #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);

Description
-----------

Each process has two interval timers, `ITIMER_REAL' and `ITIMER_PROF',
which raise the signals `SIGALRM' and `SIGPROF', respectively.  These
are typically used to provide `alarm' and profiling capabilities.

This function changes the current value of the interval timer specified
by WHICH to the values in structure VALUE.  The previous value of the
timer is returned in OVALUE if it is not a `NULL' pointer.  When the
timer expires, the appropriate signal is raised.

Please see the documentation for `signal' (*note signal::) for
restrictions on signal handlers.

If VALUE is a `NULL' pointer, `setitimer' stores the previous timer
value in OVALUE (if it is non-`NULL'), like `getitimer' does, but
otherwise does nothing.

A timer is defined by the `itimerval' structure.  If the `it_value'
member is non-zero it specifies the time to the next timer expiration.
If `it_interval' is non-zero, it specifies the value with which to
reload the timer upon expiration.  Setting `it_value' to zero disables
a timer.  Setting `it_interval' to zero causes the timer to stop after
the next expiration (assuming that `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 `value->it_interval.tv_usec' will cause the
system clock granularity to be stored and returned by the next call to
`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 `setitimer',
otherwise intervals smaller than the default PC clock speed cannot be
set with a call to `setitimer' due to rounding up to clock granularity.
To this end, an external variable `__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 `-1', which causes `setitimer' to work with 54926
microsecond granularity that corresponds to the standard 18.2Hz clock
frequency.  The library never changes the value of
`__djgpp_clock_tick_interval'.

Return Value
------------

Returns 0 on success, -1 on failure (and sets `errno').

Portability
-----------

ANSI/ISO C   No
POSIX        No

Bugs
----

This version uses `uclock' (*note uclock::) to determine the time of
expiration.  Under Windows 3.X, this fails because the OS reprograms
the timer.  Under Windows 9X, `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 `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 `SIGSEGV' or `SIGABRT', since signals were not
supported in a debugged program before DJGPP v2.03.

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);


File: libc.info,  Node: setjmp,  Next: setlinebuf,  Prev: setitimer,  Up: Alphabetical List

setjmp
======

Syntax
------

     #include <setjmp.h>

     int setjmp(jmp_buf j);

Description
-----------

This function stores the complete CPU state into J.  This information
is complete enough that `longjmp' (*note longjmp::) can return the
program to that state.  It is also complete enough to implement
coroutines.

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.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     jmp_buf j;
     if (setjmp(j))
       return;
     do_something();
     longjmp(j, 1);


File: libc.info,  Node: setlinebuf,  Next: setlocale,  Prev: setjmp,  Up: Alphabetical List

setlinebuf
==========

Syntax
------

     #include <stdio.h>

     void setlinebuf(FILE *file);

Description
-----------

This function modifies the buffering characteristics of 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 `fopen'.

Next, a buffer is allocated and the file is set to line buffering.

*Note setbuf::.  *Note setlinebuf::.  *Note setvbuf::.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     setlinebuf(stderr);


File: libc.info,  Node: setlocale,  Next: setmntent,  Prev: setlinebuf,  Up: Alphabetical List

setlocale
=========

Syntax
------

     #include <locale.h>

     char *setlocale(int category, const char *locale);

Description
-----------

This function sets part or all of the current locale.  The CATEGORY is
one of the following:

`LC_ALL'
     Set all parts of the locale.

`LC_COLLATE'
     Set the collating information.

`LC_CTYPE'
     Set the character type information.

`LC_MONETARY'
     Set the monetary formatting information.

`LC_NUMERIC'
     Set the numeric formatting information.

`LC_TIME'
     Set the time formatting information.


The LOCALE should be the name of the current locale.  Supported locales
includes user default locale (in this case settings obtained from the
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 LOCALE
is NULL, no action is performed.  If LOCALE is "", the locale is
identified by environment variables.

Due to limitations of the `country.sys' driver only the current user
locale `""' or its name in the POSIX-like form `"LL_TTECU.CP"', and
`"C"' (aka `"POSIX"') locales are supported.

The POSIX-like locale code `"LL_TTECU.CS"' consists of the ISO two
letter lowercase language code LL, the ISO two letter uppercase
territory code TT, optionally followed by the suffix `"_EURO"' for ECU
if the country has adopted the Euro as its currency unit, and the
character set CS specified by a code page number between 1 and 65534;
for example, `"de_AT.850"' for the German-speaking Austrian locale, or
`"fr_BE_EURO.850"' for the French-speaking Belgian locale using the
Euro, both using Western multilingual "Latin-1" code page number 850.

*Note localeconv::.

Return Value
------------

A static string naming the current locale for the given category, or
NULL if the requested locale is not supported.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     setlocale(LC_ALL, "C");


File: libc.info,  Node: setmntent,  Next: setmode,  Prev: setlocale,  Up: Alphabetical List

setmntent
=========

Syntax
------

     #include <mntent.h>

     FILE *setmntent(char *filename, const char *mode);

Description
-----------

This function returns an open `FILE*' pointer which can be used by
`getmntent' (*note getmntent::).  The arguments FILENAME and 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 MODE argument to
`fopen', *note 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 `<mntent.h>'.)

Return Value
------------

The `FILE*' pointer is returned.  For MS-DOS, this `FILE*' is not a
real pointer and may only be used by `getmntent'.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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");


File: libc.info,  Node: setmode,  Next: setpgid,  Prev: setmntent,  Up: Alphabetical List

setmode
=======

Syntax
------

     #include <io.h>

     int setmode(int file, int mode);

Description
-----------

This function sets the mode of the given FILE to MODE, which is either
`O_TEXT' or `O_BINARY'.  It will also set the file into either cooked
or raw mode accordingly, and set any `FILE*' objects that use this file
into text or binary mode.

When called to put FILE that refers to the console into binary mode,
`setmode' will disable the generation of the signals `SIGINT' and
`SIGQUIT' when you press, respectively, `Ctrl-<C>' and `Ctrl-<\>'
(`Ctrl-<BREAK>' will still cause `SIGINT'), because many programs that
use binary reads from the console will also want to get the `^C' and
`^\' keys.  You can use the  `__djgpp_set_ctrl_c' library function
(*note __djgpp_set_ctrl_c::) if you want `Ctrl-<C>' and `Ctrl-<\>' to
generate signals while console is read in binary mode.

Note that, for buffered streams (`FILE*'), you must call `fflush'
(*note fflush::) before `setmode', or call `setmode' before writing
anything to the file, for proper operation.

Return Value
------------

When successful, the function will return the previous mode of the
given FILE.  In case of failure, -1 is returned and `errno' is set.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     setmode(0, O_BINARY);


File: libc.info,  Node: setpgid,  Next: setpwent,  Prev: setmode,  Up: Alphabetical List

setpgid
=======

Syntax
------

     #include <unistd.h>

     int setpgid(pid_t _pid, pid_t _pgid);

Return Value
------------

-1 (EPERM) if _pgid is not your current pid, else zero.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: setpwent,  Next: setrlimit,  Prev: setpgid,  Up: Alphabetical List

setpwent
========

Syntax
------

     #include <pwd.h>

     void setpwent(void);

Description
-----------

This function reinitializes `getpwent' so that scanning will start from
the start of the list.  *Note getpwent::.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: setrlimit,  Next: setsid,  Prev: setpwent,  Up: Alphabetical List

setrlimit
=========

Syntax
------

     #include <sys/resource.h>

     int setrlimit (int rltype, const struct rlimit *rlimitp);

Description
-----------

This function sets new limit pointed to by RLIMITP on the resource
limit specified by RLTYPE.  Note that currently it always fails.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: setsid,  Next: setstate,  Prev: setrlimit,  Up: Alphabetical List

setsid
======

Syntax
------

     #include <unistd.h>

     pid_t setsid(void);

Description
-----------

This function does not do anything. It exists to assist porting from
Unix.

Return Value
------------

Return value of *note getpid::.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: setstate,  Next: settime,  Prev: setsid,  Up: Alphabetical List

setstate
========

Syntax
------

     #include <stdlib.h>

     char *setstate(char *arg_state);

Description
-----------

Restores the random number generator (*note random::) state from pointer
ARG_STATE to state array.

Return Value
------------

Pointer to old state information.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: settime,  Next: settimeofday,  Prev: setstate,  Up: Alphabetical List

settime
=======

Syntax
------

     #include <dos.h>

     void settime(struct time *ptr);

Description
-----------

This function sets the current time.

For the description of `struct time', see *Note gettime::.  Also see
*Note setdate::.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     struct time t;
     settime(&t);


File: libc.info,  Node: settimeofday,  Next: setuid,  Prev: settime,  Up: Alphabetical List

settimeofday
============

Syntax
------

     #include <time.h>

     int settimeofday(struct timeval *tp, ...);

Description
-----------

Sets the current GMT time.  For compatibility, a second argument is
accepted.  *Note gettimeofday::, for information on the structure types.

Return Value
------------

Zero if the time was set, nonzero on error.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: setuid,  Next: setvbuf,  Prev: settimeofday,  Up: Alphabetical List

setuid
======

Syntax
------

     #include <unistd.h>

     int setuid(uid_t uid);

Description
-----------

This function is simulated, since MS-DOS does not support user IDs.

Return Value
------------

If UID is equal to that returned by *note getuid::, returns zero.
Otherwise, returns -1 and sets `errno' to EPERM.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: setvbuf,  Next: sigaction,  Prev: setuid,  Up: Alphabetical List

setvbuf
=======

Syntax
------

     #include <stdio.h>

     int setvbuf(FILE *file, char *buffer, int type, int length);

Description
-----------

This function modifies the buffering characteristics of 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 `fopen'.

If the TYPE is `_IONBF', the BUFFER and LENGTH are ignored and the file
is set to unbuffered mode.

If the TYPE is `_IOLBF' or `_IOFBF', then the file is set to line or
fully buffered, respectively.  If BUFFER is `NULL', a buffer of size
SIZE is created and used as the buffer.  If BUFFER is non-`NULL', it
must point to a buffer of at least size SIZE and will be used as the
buffer.

*Note setbuf::.  *Note setbuffer::.  *Note setlinebuf::.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     setvbuf(stderr, NULL, _IOLBF, 1000);


File: libc.info,  Node: sigaction,  Next: sigaddset,  Prev: setvbuf,  Up: Alphabetical List

sigaction
=========

Syntax
------

     #include <signal.h>

     int sigaction (int sig, const struct sigaction *act,
                    struct sigaction *oact);

Description
-----------

This function allows to examine and/or change the action associated with
a signal SIG.  The `struct sigaction' structure, defined by the header
file `signal.h', is declared as follows:

      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 */
      };

The `sa_handler' member is a signal handler, see *Note signal::.  The
`sa_mask' member defines the signals, in addition to SIG, which are to
be blocked during the execution of `sa_handler'.

The `sigaction' function sets the structure pointed to by `oact' to the
current action for the signal SIG, and then sets the new action for SIG
as specified by ACT.  If the ACT argument is `NULL', `sigaction'
returns the current signal action in OACT, but doesn't change it.  If
the OACT argument is a `NULL' pointer, it is ignored.  Thus, passing
`NULL' pointers for both `act' and `oact' is a way to see if SIG is a
valid signal number on this system (if not, `sigaction' will return -1
and set `errno').

Return Value
------------

0 on success, -1 for illegal value of SIG.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: sigaddset,  Next: sigdelset,  Prev: sigaction,  Up: Alphabetical List

sigaddset
=========

Syntax
------

     #include <signal.h>

     int sigaddset (sigset_t *set, int signo)

Description
-----------

This function adds the individual signal specified by SIGNO the set of
signals pointed to by SET.

Return Value
------------

0 upon success, -1 if SET is a NULL pointer, or if SIGNO is specifies
an unknown signal.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: sigdelset,  Next: sigemptyset,  Prev: sigaddset,  Up: Alphabetical List

sigdelset
=========

Syntax
------

     #include <signal.h>

     int sigdelset (sigset_t *set, int signo)

Description
-----------

This function removes the individual signal specified by SIGNO from the
set of signals pointed to by SET.

Return Value
------------

0 upon success, -1 if SET is a NULL pointer, or if SIGNO is specifies
an unknown signal.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: sigemptyset,  Next: sigfillset,  Prev: sigdelset,  Up: Alphabetical List

sigemptyset
===========

Syntax
------

     #include <signal.h>

     int sigemptyset (sigset_t *set)

Description
-----------

This function initializes the set of signals pointed to by SET to
exclude all signals known to the DJGPP runtime system.  Such an empty
set, if passed to `sigprocmask' (*note sigprocmask::), will cause all
signals to be passed immediately to their handlers.

Return Value
------------

0 upon success, -1 if SET is a NULL pointer.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: sigfillset,  Next: sigismember,  Prev: sigemptyset,  Up: Alphabetical List

sigfillset
==========

Syntax
------

     #include <signal.h>

     int sigfillset (sigset_t *set)

Description
-----------

This function initializes the set of signals pointed to by SET to
include all signals known to the DJGPP runtime system.  Such a full
set, if set by `sigprocmask' (*note 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
`SIGABRT..SIGTRAP'; software interrupts and/or user-defined signals
aren't included.

Return Value
------------

0 upon success, -1 if SET is a NULL pointer.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------


       sigset_t full_set, prev_set;

       sigfillset (&full_set);
       sigprocmask (SIG_UNBLOCK, &full_set, &prev_set);


File: libc.info,  Node: sigismember,  Next: siglongjmp,  Prev: sigfillset,  Up: Alphabetical List

sigismember
===========

Syntax
------

     #include <signal.h>

     int sigismember (sigset_t *set, int signo)

Description
-----------

This function checks whether the signal specified by SIGNO is a member
of the set of signals pointed to by SET.

Return Value
------------

1 if the specified signal is a member of the set, 0 if it isn't, or if
SIGNO specifies an unknown signal, -1 if SET is a NULL pointer.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: siglongjmp,  Next: signal,  Prev: sigismember,  Up: Alphabetical List

siglongjmp
==========

Syntax
------

     #include <setjmp.h>

     void	siglongjmp(sigjmp_buf env, int val);

Description
-----------

*Note longjmp::.

Return Value
------------

This function does not return.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: signal,  Next: signbit,  Prev: siglongjmp,  Up: Alphabetical List

signal
======

Syntax
------

     #include <signal.h>

     void	(*signal(int sig, void (*func)(int)))(int);

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
`Ctrl-<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 `<signal.h>' (see below).  Every signal is given
a mnemonic which you should use for portable programs.

By default, signal `SIGQUIT' is discarded.  This is so programs ported
from other DOS environments, where `SIGQUIT' is generally not
supported, continue to work as they originally did.  If you want
`SIGQUIT' to abort with a traceback, install `__djgpp_traceback_exit'
as its handler (*note __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 `_exit' (*note _exit::).  As an exception, the default handler
for the signal `SIGINT' doesn't print the traceback, and calls `exit'
instead of `_exit', when the INTR key (`Ctrl-C' by default) is pressed,
so that programs could be shut down safely in this manner.  `SIGINT'
raised by `Ctrl-<BREAK>' does generate the traceback.

The function `signal' allows you to change the default behavior for a
specific signal.  It registers FUNC as a signal handler for signal
number 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 `longjmp' (*note 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 `dbgsig' in
`src/debug/common/dbgcom.c' in the DJGPP sources.

You may pass `SIG_DFL' as the value of FUNC to reset the signal
handling for the signal SIG to default (also *Note
__djgpp_exception_toggle::, for a quick way to restore all the signals'
handling to default), `SIG_ERR' to force an error when that signal
happens, or `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 `signal', assign values to data objects of
type `volatile sig_atomic_t' (defined as `int' on `<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), *Note locking memory regions: __dpmi_lock_linear_region.
Handlers for software interrupts can also terminate by calling `abort',
`exit' or `longjmp'.

The following signals are defined on `<signal.h>':

`SIGABRT'
     The Abort signal.  Currently only used by the `assert' macro to
     terminate the program when an assertion fails (*note assert::),
     and by the `abort' function (*note abort::).

`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.  *Note
     _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 *Note _control87::.

`SIGILL'
     The Invalid Execution signal.  Currently only generated for
     unknown/invalid exceptions.

`SIGINT'
     The Interrupt signal.  Generated when an INTR key (`Ctrl-C' by
     default) or `Ctrl-<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 `setmode' (*note setmode::), generation of `SIGINT'
     as result of `Ctrl-C' key is disabled.  This is so for programs
     (such as Emacs) which want to be able to read the `^C' character
     as any other character.  Use the library function
     `__djgpp_set_ctrl_c' to restore `SIGINT' generation when `Ctrl-C'
     is hit, if you need this.  *Note __djgpp_set_ctrl_c::, for details
     on how this should be done.  `Ctrl-<BREAK>' always generates
     `SIGINT'.

     DJGPP hooks the keyboard hardware interrupt (Int 09h) to be able to
     generate `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 `SIGINT' can be changed with a
     call to `__djgpp_set_sigint_key' function.  *Note
     __djgpp_set_sigint_key::.

`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.

`SIGTERM'
     The Termination Request signal.  Currently unused.

     The signals below this are not defined by ANSI C, and cannot be
     used when compiling under `-ansi' option to `gcc'.

`SIGALRM'
     The Alarm signal.  Generated after certain time period has passed
     after a call to `alarm' library function (*note alarm::).

`SIGHUP'
     The Hang-up signal.  Currently unused.

`SIGKILL'
     The Kill signal.  Currently unused.

`SIGPIPE'
     The Broken Pipe signal.  Currently unused.

`SIGQUIT'
     The Quit signal.  Generated when the QUIT key (`Ctrl-\' by default)
     is hit.  The key that raises the signal can be changed with a call
     to `__djgpp_set_sigquit_key' function.  *Note
     __djgpp_set_sigquit_key::.  By default, `SIGQUIT' is discarded,
     even if its handler is `SIG_DFL', so that DOS programs which don't
     expect it do not break.  You can change the effect of `SIGQUIT' to
     abort with traceback by installing `__djgpp_traceback_exit' as its
     handler.  *Note __djgpp_traceback_exit::.

     DJGPP hooks the keyboard hardware interrupt (Int 09h) to be able to
     generate `SIGQUIT' in response to the QUIT key; you should be
     aware of this when you install a handler for the keyboard
     interrupt.

`SIGUSR1'
     User-defined signal no. 1.

`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 `-ansi' or `-posix' options to
     `gcc'.

`SIGTRAP'
     The Trap Instruction signal.  Generated in response to the Debugger
     Exception (Int 01h) or Breakpoint Exception (Int 03h).

`SIGNOFP'
     The No Co-processor signal.  Generated if a co-processor
     (floating-point) instruction is encountered when no co-processor
     is installed (Int 07h).

`SIGTIMR'
     The Timer signal.  Used by the `setitimer' and `alarm' functions
     (*Note setitimer::, and *note alarm::).

`SIGPROF'
     The Profiler signal.  Used by the execution profile gathering code
     in a program compiled with `-pg' option to `gcc'.


Return Value
------------

The previous handler for signal SIG, or `SIG_ERR' if the value of SIG
is outside legal limits.

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 `read' (or `scanf', or
`gets') to read text from the console and press `Ctrl-C', you will have
to press `Enter' to terminate the `read' call to cause the signal
handler for `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.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: signbit,  Next: __signbitd,  Prev: signal,  Up: Alphabetical List

signbit
=======

Syntax
------

     #include <math.h>

     int signbit(x);

Description
-----------

The macro `signbit' returns 0 if the sign of the mantissa of the
floating point number X is positive else it returns non-zero.

Return Value
------------

zero for positive floating point numbers; non-zero for negative
floating point numbers.

Portability
-----------

ANSI/ISO C   C99; not C89

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");


File: libc.info,  Node: __signbitd,  Next: __signbitf,  Prev: signbit,  Up: Alphabetical List

__signbitd
==========

Syntax
------

     #include <math.h>

     int __signbitd(double x);

Description
-----------

Returns 0 if the sign of the mantissa of the floating point number X is
positive else it returns non-zero.  You should use the type generic
macro `signbit' (*note signbit::) instead of this function.

Return Value
------------

zero for positive floating point numbers; non-zero for negative
floating point numbers.

Portability
-----------

ANSI/ISO C   C99; not C89

Example
-------


     printf("double value is %s.\n", (__signbitd(0.0)) ? "negative" : "positive");


File: libc.info,  Node: __signbitf,  Next: __signbitld,  Prev: __signbitd,  Up: Alphabetical List

__signbitf
==========

Syntax
------

     #include <math.h>

     int __signbitf(float x);

Description
-----------

Returns 0 if the sign of the mantissa of the floating point number X is
positive else it returns non-zero.  You should use the type generic
macro `signbit' (*note signbit::) instead of this function.

Return Value
------------

zero for positive floating point numbers; non-zero for negative
floating point numbers.

Portability
-----------

ANSI/ISO C   C99; not C89

Example
-------


     printf("float value is %s.\n", (__signbitf(0.0F)) ? "negative" : "positive");


File: libc.info,  Node: __signbitld,  Next: sigpending,  Prev: __signbitf,  Up: Alphabetical List

__signbitld
===========

Syntax
------

     #include <math.h>

     int __signbitld(long double x);

Description
-----------

Returns 0 if the sign of the mantissa of the floating point number X is
positive else it returns non-zero.  You should use the type generic
macro `signbit' (*note signbit::) instead of this function.

Return Value
------------

zero for positive floating point numbers; non-zero for negative
floating point numbers.

Portability
-----------

ANSI/ISO C   C99; not C89

Example
-------


     printf("long double value is %s.\n", (__signbitld(0.0L)) ? "negative" : "positive");


File: libc.info,  Node: sigpending,  Next: sigprocmask,  Prev: __signbitld,  Up: Alphabetical List

sigpending
==========

Syntax
------

     #include <signal.h>

     int sigpending (sigset_t *set)

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 (*note
sigprocmask::).  The bit-mapped value which describes the pending
signals is stored in the structure pointed to by SET.  You can use the
`sigismember' function (*note sigismember::) to see what individual
signals are pending.

Return Value
------------

0 on success, -1 on failure (and errno set to `EFAULT').

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

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);
         }


File: libc.info,  Node: sigprocmask,  Next: sigsetjmp,  Prev: sigpending,  Up: Alphabetical List

sigprocmask
===========

Syntax
------

     #include <signal.h>

     int sigprocmask (int how, const sigset_t *new_set, sigset_t *old_set)

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.  (*Note sigismember::, *Note sigaddset::, *Note
sigdelset::, *Note sigemptyset::, *Note 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 `sigprocmask'.  Thus blocking a
signal is an alternative to ignoring it (by setting its handler to
`SIG_IGN', *note signal::), but has an advantage of not missing the
signal entirely.

The value of the argument HOW determines the operation: if it is
`SIG_BLOCK', the set pointed to by the argument NEW_SET is _added_ to
the current signal mask.  If the value is `SIG_UNBLOCK', the set
pointed to by NEW_SET is _removed_ from the current signal mask.  If
the value is `SIG_SETMASK', the current mask is _replaced_ by the set
pointed to by NEW_SET.

If the argument OLD_SET is not `NULL', the previous mask is stored in
the space pointed to by OLD_SET.  If the value of the argument NEW_SET
is `NULL', the value of HOW is not significant and the process signal
mask is unchanged; thus, the call with a zero 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 `raise') before the call
to `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 `SIGSEGV' signal); for these,
`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 `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 `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.

Return Value
------------

0 on success, -1 for illegal value of SIG or illegal address in NEW_SET
or OLD_SET.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

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;
     }


File: libc.info,  Node: sigsetjmp,  Next: sin,  Prev: sigprocmask,  Up: Alphabetical List

sigsetjmp
=========

Syntax
------

     #include <setjmp.h>

     int	sigsetjmp(sigjmp_buf env, int savemask);

Description
-----------

*Note setjmp::.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: sin,  Next: sincos,  Prev: sigsetjmp,  Up: Alphabetical List

sin
===

Syntax
------

     #include <math.h>

     double sin(double x);

Description
-----------

This function computes the sine of X (which should be given in radians).

Return Value
------------

The sine of X.  If the absolute value of X is finite but greater than
or equal to 2^63, the value is 0 (since for arguments that large each
bit of the mantissa is more than `Pi').  If the value of X is infinite
or `NaN', the return value is `NaN' and `errno' is set to `EDOM'.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Accuracy
--------

In general, this function's relative accuracy is about 1.7*10^(-16),
which is close to the machine precision for a `double'.  However, for
arguments very close to `Pi' and its odd multiples, the relative
accuracy can be many times worse, due to loss of precision in the
internal FPU computations.  Since sin(Pi) is zero, the absolute
accuracy is still very good; but if your program needs to preserve high
_relative_ accuracy for such arguments, link with `-lm' and use the
version of `sin' from `libm.a' which does elaborate argument reduction,
but is about three times slower.


File: libc.info,  Node: sincos,  Next: sinh,  Prev: sin,  Up: Alphabetical List

sincos
======

Syntax
------

     #include <math.h>

     void   sincos(double x, double *sine, double *cosine);

Description
-----------

This function computes the cosine and the sine of X in a single call,
and stores the results in the addresses pointed to by COSINE and SINE,
respectively.  Since the function exploits a machine instruction that
computes both cosine and sine simultaneously, it is faster to call
`sincos' than to call `cos' and `sin' for the same argument.

If the absolute value of X is finite but greater than or equal to 2^63,
the value stored in *COSINE is 1 and the value stored in *SINE is 0
(since for arguments that large each bit of the mantissa is more than
`Pi').  If the value of X is infinite or `NaN', `NaN' is stored in both
*COSINE and *SINE, and `errno' is set to `EDOM'.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: sinh,  Next: sleep,  Prev: sincos,  Up: Alphabetical List

sinh
====

Syntax
------

     #include <math.h>

     double sinh(double x);

Description
-----------

This function computes the hyperbolic sine of X.

Return Value
------------

The hyperbolic sine of X.  If the absolute value of X is finite but so
large that the result would overflow a `double', the return value is
`Inf' with the same sign as X, and `errno' is set to `ERANGE'.  If X is
either a positive or a negative infinity, the result is `+Inf' with the
same sign as X, and `errno' is not changed.  If X is `NaN', the return
value is `NaN' and `errno' is set to `EDOM'.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: sleep,  Next: snprintf,  Prev: sinh,  Up: Alphabetical List

sleep
=====

Syntax
------

     #include <unistd.h>

     unsigned sleep(unsigned seconds);

Description
-----------

This function causes the program to pause for SECONDS seconds.

Return Value
------------

The number of seconds that haven't passed (i.e. always zero)

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     sleep(5);


File: libc.info,  Node: snprintf,  Next: __solve_dir_symlinks,  Prev: sleep,  Up: Alphabetical List

snprintf
========

Syntax
------

     #include <stdio.h>

     int snprintf (char *buffer, size_t n, const char *format, ...);

Description
-----------

This function works similarly to `sprintf()' (*note sprintf::), but the
size N of the BUFFER is also taken into account.  This function will
write N - 1 characters.  The Nth character is used for the terminating
nul.  If N is zero, BUFFER is not touched.

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 N is `INT_MAX'.  `INT_MAX' is defined in
`<limits.h>'.  -1 is returned and `errno' is set to `EFBIG', if N is
greater than this limit.

Portability
-----------

ANSI/ISO C   C89; C99; (see note 1)

Notes:

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



File: libc.info,  Node: __solve_dir_symlinks,  Next: __solve_symlinks,  Prev: snprintf,  Up: Alphabetical List

__solve_dir_symlinks
====================

Syntax
------

     #include <libc/symlink.h>

     int __solve_dir_symlinks(const char *symlink_path, char *real_path);

Description
-----------

This function resolves given symlink in SYMLINK_PATH--all path
components *except* the last one and all symlink levels are resolved.
If SYMLINK_PATH does not contain symlinks at all, it is simply copied
to REAL_PATH.

REAL_PATH should be of size `FILENAME_MAX', to contain the maximum
possible length of path.

Return Value
------------

Zero in case of error (and `errno' set to the appropriate error code),
non-zero in case of success.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: __solve_symlinks,  Next: sound,  Prev: __solve_dir_symlinks,  Up: Alphabetical List

__solve_symlinks
================

Syntax
------

     #include <libc/symlink.h>

     int __solve_symlinks(const char *symlink_path, char *real_path);

Description
-----------

This function fully resolves given symlink in SYMLINK_PATH--all path
components and all symlink levels are resolved.  The returned path in
REAL_PATH is guaranteed to be symlink-clean and understandable by DOS.
If SYMLINK_PATH does not contain symlinks at all, it is simply copied
to REAL_PATH.

REAL_PATH should be of size `FILENAME_MAX', to contain the maximum
possible length of path.

Return Value
------------

Zero in case of error (and `errno' set to the appropriate error code),
non-zero in case of success.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: sound,  Next: spawn*,  Prev: __solve_symlinks,  Up: Alphabetical List

sound
=====

Syntax
------

     #include <pc.h>

     void		sound(int _frequency);

Description
-----------

Enables the PC speaker at the given frequency.  The argument _FREQUENCY
should be given in Hertz units.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: spawn*,  Next: sprintf,  Prev: sound,  Up: Alphabetical List

spawn*
======

Syntax
------

     #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[]);

Description
-----------

These functions run other programs.  The PATH points to the program to
run, and may optionally include its extension.  These functions will
look for a file PATH with the extensions `.com', `.exe', `.bat', and
`.btm'; if none are found, neither in the current directory nor along
the `PATH', they will look for PATH itself.

`.com' programs are invoked via the usual DOS calls; DJGPP `.exe'
programs are invoked in a way that allows long command lines to be
passed; other `.exe' programs are invoked via DOS; `.bat' and `.btm'
programs are invoked via the command processor given by the `COMSPEC'
environment variable; `.sh', `.ksh' programs and programs with any
other extensions that have `#!' 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 `/bin/sh', the `spawn' functions will
additionally look them up on the `PATH'; this allows to run Unix
scripts without editing, if you have a shell installed somewhere along
your `PATH'.)  Any non-recognizable files will be also invoked via DOS
calls.

*WARNING!*  DOS is rather stupid in invoking programs: if the file
doesn't have the telltale "MZ" signature of the `.exe' style programs,
DOS assumes it is a `.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 `stat' (*note stat::) or
`_is_executable' (*note _is_executable::) library functions.

Note that built-in commands of the shells can _not_ be invoked via
these functions; use `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 `l' functions (like `spawnl') take a list of
arguments, with a `NULL' at the end of the list.  This is useful when
you know how many argument there will be ahead of time.  The `v'
functions (like `spawnv') take a pointer to a list of arguments, which
also must be `NULL'-terminated.  This is useful when you need to
compute the number of arguments at runtime.

In either case, you may also specify `e' to indicate that you will be
giving an explicit environment, else the current environment is used.
You may also specify `p' to indicate that you would like `spawn*' to
search the `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 _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 `PE-COFF' format), or when the system shell
is `4DOS' or `NDOS' and the shell is called to run the command, command
lines longer than 126 characters are passed via the environment
variable `CMDLINE'.

*Note exec*::.

Return Value
------------

If successful and `mode' is `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.
`COMMAND.COM' is notorious for returning 0 even if it couldn't run the
command.

If successful and MODE is `P_OVERLAY', these functions will not return.

If there is an error (e.g., the program specified as `argv[0]' cannot
be run, or the command line is too long), these functions return -1 and
set `errno' to indicate the error.  If the child program was
interrupted by <Ctrl-C> or a Critical Device error, `errno' is set to
`EINTR' (even if the child's exit code is 0), and bits 8-17 of the
return value are set to `SIGINT' or `SIGABRT', accordingly.  Note that
you must set the signal handler for `SIGINT' to `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.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: sprintf,  Next: sqrt,  Prev: spawn*,  Up: Alphabetical List

sprintf
=======

Syntax
------

     #include <stdio.h>

     int sprintf(char *buffer, const char *format, ...);

Description
-----------

Sends formatted output from the arguments (...) to the BUFFER.  *Note
printf::.

To avoid buffer overruns, it is safer to use `snprintf()' (*note
snprintf::).

Return Value
------------

The number of characters written.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: sqrt,  Next: srand,  Prev: sprintf,  Up: Alphabetical List

sqrt
====

Syntax
------

     #include <math.h>

     double sqrt(double x);

Description
-----------

This function computes the square root of X.

Return Value
------------

The square root of X.  If X is negative or a `NaN', the return value is
`NaN' and `errno' is set to `EDOM'.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: srand,  Next: srandom,  Prev: sqrt,  Up: Alphabetical List

srand
=====

Syntax
------

     #include <stdlib.h>

     void srand(unsigned seed);

Description
-----------

Initializes the random number generator for `rand()'.  If you pass the
same seed, `rand()' will return the same sequence of numbers.  You can
seed from `time' (*note time::) or `rawclock' (*note rawclock::).

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     /* random pause */
     srand(time(0));
     for (i=rand(); i; i--);


File: libc.info,  Node: srandom,  Next: sscanf,  Prev: srand,  Up: Alphabetical List

srandom
=======

Syntax
------

     #include <stdlib.h>

     int srandom(int seed);

Description
-----------

Initializes the random number generator (*note random::). Passing the
same SEED results in `random' returning predictable sequences of
numbers, unless *note initstate:: or *note setstate:: are called.

Return Value
------------

Zero.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     srandom(45);


File: libc.info,  Node: sscanf,  Next: Stack overflow handler,  Prev: srandom,  Up: Alphabetical List

sscanf
======

Syntax
------

     #include <stdio.h>

     int sscanf(const char *string, const char *format, ...);

Description
-----------

This function scans formatted text from the STRING and stores it in the
variables pointed to by the arguments.  *Note scanf::.

Return Value
------------

The number of items successfully scanned.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: Stack overflow handler,  Next: stackavail,  Prev: sscanf,  Up: Alphabetical List

Stack overflow handler
======================

Syntax
------

     extern unsigned int __djgpp_stack_overflow_eip;
     void __djgpp_stack_overflow_exit(void);

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.

Return Value
------------

This function does not return.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: stackavail,  Next: stat,  Prev: Stack overflow handler,  Up: Alphabetical List

stackavail
==========

Syntax
------

     #include <stdlib.h>

     int stackavail(void);

Description
-----------

This function returns the number of bytes that are available on the
stack.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     printf("Available stack size is %d bytes\n", stackavail());


File: libc.info,  Node: stat,  Next: statfs,  Prev: stackavail,  Up: Alphabetical List

stat
====

Syntax
------

     #include <sys/stat.h>

     int stat(const char *file, struct stat *sbuf);

Description
-----------

This function obtains the status of the file FILE and stores it in
SBUF.  `stat' follows symbolic links.  To get information about a
symbolic link, use `lstat' (*note lstat::) instead.

SBUF has this structure:

     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:) */
     };

The `st_atime', `st_ctime' and `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(1).  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 `stat' sets the `st_atime' member to the same value
as `st_mtime' if the time part of `st_atime' returned by the filesystem
is zero (to prevent the situation where the file appears to have been
created _after_ it was last accessed, which doesn't look good).

The `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 `st_size' as an unsigned value.

For some drives `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 `struct stat' are very expensive to compute.  If your
application is a heavy user of `stat' and is too slow, you can disable
computation of the members your application doesn't need, as described
in *Note _djstat_flags::.

Return Value
------------

Zero on success, nonzero on failure (and `errno' set).

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     struct stat s;
     stat("data.txt", &s);
     if (S_ISDIR(s.st_mode))
       printf("is directory\n");

Implementation Notes
--------------------

Supplying a 100% Unix-compatible `stat' function under DOS is an
implementation nightmare.  The following notes describe some of the
obscure points specific to `stat's behavior in DJGPP.

1. The `drive' for character devices (like `con', `/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 `st_inode' field
will be _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 `stat', `fstat' and `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 `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 `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 `_djstat_flags' (*note _djstat_flags::) controls what
hard-to-get fields of `struct stat' are needed by the application.

7. `stat' should not be used to get an up-to-date info about a file
which is open and has been written to, because `stat' will only return
correct data after the file is closed.  Use `fstat' (*note fstat::)
while the file is open.  Alternatively, you can call `fflush' and
`fsync' to make the OS flush all the file's data to the disk, before
calling `stat'.

8. The number of links `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.

---------- Footnotes ----------

(1) Even when long file names _are_ supported, the three time values
returned by `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.


File: libc.info,  Node: statfs,  Next: _status87,  Prev: stat,  Up: Alphabetical List

statfs
======

Syntax
------

     #include <sys/vfs.h>

     int statfs(const char *filename, struct statfs *buf);

Description
-----------

This function returns information about the given "filesystem".  The
drive letter of the given FILENAME, or the default drive if none is
given, is used to retrieve the following structure:

     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 */
     };

Note that if INT 21h is hooked by a TSR, the total size is limited to
approximately 2GB (*note statvfs::).

Note that there is a POSIX-compliant function `statvfs' (*note
statvfs::), which returns similar information.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: _status87,  Next: statvfs,  Prev: statfs,  Up: Alphabetical List

_status87
=========

Syntax
------

     #include <float.h>

     unsigned int _status87(void);

Description
-----------

Returns the status word of the FPU, which indicate the results of the
most recently completed FPU operation:

     ---- ---- ---- ---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

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: statvfs,  Next: _stklen,  Prev: _status87,  Up: Alphabetical List

statvfs
=======

Syntax
------

     #include <sys/types.h>
     #include <sys/statvfs.h>

     int statvfs (const char *path, struct statvfs *sbuf);

Description
-----------

This function returns information about the "filesystem" (FS)
containing PATH and stores it in SBUF, which has the structure below:

     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 */
     };

Note that if INT 21h is hooked by a TSR, the total size is limited to
approximately 2GB.  TSRs that hook INT 21h include:

   * CD-ROM drivers;

   * command-line enhancers such as CMDEDIT and Microsoft's DOSEdit.

These may be loaded by `autoexec.bat' or `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.

Return Value
------------

Zero on success, nonzero on failure (and `errno' set).

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)

Notes:

  1. See the comments on the fundamental block size above.



File: libc.info,  Node: _stklen,  Next: stpcpy,  Prev: statvfs,  Up: Alphabetical List

_stklen
=======

Syntax
------

     extern int _stklen;

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.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     int _stklen = 256000;


File: libc.info,  Node: stpcpy,  Next: stpncpy,  Prev: _stklen,  Up: Alphabetical List

stpcpy
======

Syntax
------

     #include <string.h>

     char *stpcpy(char *_dest, const char *_src);

Description
-----------

Like `strcpy' (*note strcpy::), but return value different.

Return Value
------------

Returns a pointer to the trailing NUL in DEST.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: stpncpy,  Next: strcasecmp,  Prev: stpcpy,  Up: Alphabetical List

stpncpy
=======

Syntax
------

     #include <string.h>

     char *stpncpy(char *_dest, const char *_src, size_t _n);

Description
-----------

Copies exactly _N characters from _SRC to _DEST.  If need be, _DEST is
padded with zeros to make _N characters.  Like `strncpy' (*note
strncpy::), but return value different.

Return Value
------------

Returns a pointer to the character following the last nonzero written.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: strcasecmp,  Next: strcat,  Prev: stpncpy,  Up: Alphabetical List

strcasecmp
==========

Syntax
------

     #include <string.h>

     int strcasecmp(const char *s1, const char *s2);

Description
-----------

This function compares the two strings, disregarding case.

Return Value
------------

Zero if they're the same, nonzero if different, the sign indicates
"order".

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     if (strcasecmp(arg, "-i") == 0)
       do_include();


File: libc.info,  Node: strcat,  Next: strchr,  Prev: strcasecmp,  Up: Alphabetical List

strcat
======

Syntax
------

     #include <string.h>

     char *strcat(char *s1, const char *s2);

Description
-----------

This function concatenates S2 to the end of S1.

Return Value
------------

S1

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     char buf[100] = "hello";
     strcat(buf, " there");


File: libc.info,  Node: strchr,  Next: strcmp,  Prev: strcat,  Up: Alphabetical List

strchr
======

Syntax
------

     #include <string.h>

     char *strchr(const char *s, int c);

Description
-----------

This function returns a pointer to the first occurrence of C in S.
Note that if C is `NULL', this will return a pointer to the end of the
string.

Return Value
------------

A pointer to the character, or `NULL' if it wasn't found.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     char *slash = strchr(filename, '/');


File: libc.info,  Node: strcmp,  Next: strcoll,  Prev: strchr,  Up: Alphabetical List

strcmp
======

Syntax
------

     #include <string.h>

     int strcmp(const char *s1, const char *s2);

Description
-----------

This function compares S1 and S2.

Return Value
------------

Zero if the strings are equal, a positive number if S1 comes after S2
in the ASCII collating sequence, else a negative number.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     if (strcmp(arg, "-i") == 0)
       do_include();


File: libc.info,  Node: strcoll,  Next: strcpy,  Prev: strcmp,  Up: Alphabetical List

strcoll
=======

Syntax
------

     #include <string.h>

     int strcoll(const char *s1, const char *s2);

Description
-----------

This function compares S1 and S2, using the collating sequences from
the current locale.

Return Value
------------

Zero if the strings are equal, a positive number if S1 comes after S2
in the collating sequence, else a negative number.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     while (strcoll(var, list[i]) < 0)
       i++;


File: libc.info,  Node: strcpy,  Next: strcspn,  Prev: strcoll,  Up: Alphabetical List

strcpy
======

Syntax
------

     #include <string.h>

     char *strcpy(char *s1, const char *s2);

Description
-----------

This function copies S2 into S1.

Return Value
------------

S1

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     char buf[100];
     strcpy(buf, arg);


File: libc.info,  Node: strcspn,  Next: strdup,  Prev: strcpy,  Up: Alphabetical List

strcspn
=======

Syntax
------

     #include <string.h>

     size_t strcspn(const char *s1, const char *set);

Description
-----------

This function finds the first character in S1 that matches any
character in SET.  Note that the `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.

Return Value
------------

The index of the found character.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     int i = strcspn(command, "<>|");
     if (command[i])
       do_redirection();


File: libc.info,  Node: strdup,  Next: strerror,  Prev: strcspn,  Up: Alphabetical List

strdup
======

Syntax
------

     #include <string.h>

     char * strdup (const char *source);

Description
-----------

Returns a newly allocated area of memory that contains a duplicate of
the string pointed to by SOURCE.  The memory returned by this call must
be freed by the caller.

Return Value
------------

Returns the newly allocated string, or NULL if there is no more memory.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     char *foo()
     {
       return strdup("hello");
     }


File: libc.info,  Node: strerror,  Next: strerror_r,  Prev: strdup,  Up: Alphabetical List

strerror
========

Syntax
------

     #include <string.h>

     char *strerror(int error);

Description
-----------

This function returns a string that describes the ERROR.

Return Value
------------

A pointer to a static string that should not be modified or free'd.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     if (f=fopen("foo", "r") == 0)
       printf("Error! %s: %s\n", "foo", strerror(errno));


File: libc.info,  Node: strerror_r,  Next: strftime,  Prev: strerror,  Up: Alphabetical List

strerror_r
==========

Syntax
------

     #include <string.h>

     int strerror_r(int error, char *strerrbuf, size_t buflen);

Description
-----------

This function fills the STRERRBUF of length BUFLEN with a string that
describes the ERROR.

Return Value
------------

0 if successful or `ERANGE' if BUFLEN is too small.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

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);
       }


File: libc.info,  Node: strftime,  Next: stricmp,  Prev: strerror_r,  Up: Alphabetical List

strftime
========

Syntax
------

     #include <time.h>

     size_t strftime(char *buf, size_t n, const char *format,
                     const struct tm *time_info);

Description
-----------

This function formats the time data in TIME_INFO according to the given
FORMAT and stores it in BUF, not exceeding N bytes.

The format string is like `printf' in that any character other than `%'
is added to the output string, and for each character following a `%' 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:

`%A'
     The full weekday name (`Friday')

`%a'
     The abbreviated weekday name (`Fri')

`%B'
     The full month name (`October')

`%b'
`%h'
     The abbreviated month name (`Oct')

`%C'
     The century number (year/100) as a 2-digit integer (`19')

`%c'
     Short for `%m/%d/%y %H:%M:%S' (`10/01/93 15:30:34')

`%D'
     Short for `%m/%d/%y' (`10/01/93')

`%d'
     The day of the month (1-31), zero padded to two characters (`02')

`%Ex'
     In some locales, the `E' modifier selects alternative
     representations of certain conversion specifiers `x'.  But in the
     "C" locale supported by djgpp, it is ignored, and treated as `%x'.
     E.G.: `%EC' will be mapped to `%C'.

`%e'
     The day of the month (1-31), blank padded to two characters (` 2')

`%F'
     The ISO 8601:2000 date format, in the form `%Y-%m-%d'
     (`1993-10-01')

`%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 `%V').  This has the same format and value as `%Y',
     except that if the ISO week number belongs to the previous or next
     year, that year is used instead (`1993')

`%g'
     Like `%G', but without century, i.e., with a 2-digit year (`93')

`%H'
     The hour (0-24), zero padded to two characters (`15')

`%I'
     The hour (1-12), zero padded to two characters (`03')

`%j'
     The Julian day (1-366), zero padded to three characters (`275')

`%k'
     The hour (0-24), space padded to two characters (`15')

`%l'
     The hour (1-12), space padded to two characters(` 3')

`%M'
     The minutes (0-59), zero padded to two characters (`30')

`%m'
     The month (1-12), zero padded to two characters (`10')

`%n'
     A newline (`\n')

`%Ox'
     In some locales, the `O' modifier selects alternative digit
     characters for certain conversion specifiers `x'.  But in the "C"
     locale supported by djgpp, it is ignored, and treated as `%x'.
     E.G.: `%OH' will be mapped to `%H'.

`%p'
     AM or PM (`PM')

`%P'
     Like `%p' but in lowercase: am or pm (`pm')

`%R'
     Short for `%H:%M' (`15:30')

`%r'
     Short for `%I:%M:%S %p' (`03:30:35 PM')

`%S'
     The seconds (0-60), zero padded to two characters (`35')

`%s'
     The seconds since the Epoch, i.e., since 1970-01-01 00:00:00 UTC
     (`749489433')

`%T'
     Short for `%H:%M:%S' (`15:30:35')

`%t'
     A tab (`\t')

`%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 (`39')

`%u'
     The day of the week (1-7), Monday being 1 (`6')

`%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 (`39')

`%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 (`39')

`%w'
     The day of the week (0-6), Sunday being 0 (`5')

`%x'
     Date represented according to the current locale.

`%X'
     Time represented according to the current locale.

`%y'
     The year (00-99) of the century (`93')

`%Y'
     The year, zero padded to four digits (`1993')

`%Z'
     The timezone abbreviation (`EDT')

`%z'
     The time-zone as hour offset from GMT in the ISO 8601:2000
     standard format (`+hhmm' or `-hhmm'), or by no characters if no
     timezone is determinable.  Required to emit RFC 822-conformant
     dates using `%a, %d %b %Y  %H:%M:%S  %z' (`Fri, 01 Oct 1993
     03:30:34  -0500')

`%+'
     The date and time in date(1) format.  Not supported in djgpp

`%%'
     A percent symbol (`%')


The following flag characters, preceding the conversion specifier
characters described above, are permitted:

`_'
     (underscore) Pad a numeric result string with spaces

`-'
     (dash) Do not pad a numeric result string

`0'
     Pad a numeric result string with zeros even if the conversion
     specifier character uses space-padding by default

`^'
     Convert alphabetic characters in result string to upper case

`#'
     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).


Return Value
------------

The number of characters stored.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

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);


File: libc.info,  Node: stricmp,  Next: strlcat,  Prev: strftime,  Up: Alphabetical List

stricmp
=======

Syntax
------

     #include <string.h>

     int stricmp(const char *s1, const char *s2);

Description
-----------

This function compares the two strings, disregarding case.

Return Value
------------

Zero if they're the same, nonzero if different, the sign indicates
"order".

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     if (stricmp(arg, "-i") == 0)
       do_include();


File: libc.info,  Node: strlcat,  Next: strlcpy,  Prev: stricmp,  Up: Alphabetical List

strlcat
=======

Syntax
------

     #include <string.h>

     size_t strlcat (char *dest, const char *src, size_t size);

Description
-----------

Concatenate characters from SRC to DEST and nul-terminate the resulting
string.  As much of SRC is copied into DEST as there is space for.

SIZE should be the size of the destination string buffer DEST plus the
space for the nul-terminator.  SIZE may be computed in many cases using
the `sizeof' operator.

`strlcat' may be used as a less ambiguous alternative to `strncat'
(*note strncat::).  `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 DEST is not nul-terminated, then DEST is not modified.

`strlcat' will not examine more than SIZE characters of DEST.  This is
to avoid overrunning the buffer DEST.

If DEST and 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 `strlcat' and `strlcpy' (*note
strlcpy::) is available on the web:
`http://www.openbsd.org/papers/strlcpy-paper.ps'.

Return Value
------------

The length of the string that `strlcat' tried to create is returned,
whether or not `strlcat' could store it in DEST.  If all of SRC was
concatenated to DST, the return value will be less than SIZE.

If DEST is not nul-terminated, then `strlcat' will consider DEST to be
SIZE in length and return SIZE plus the length of SRC.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `somestring' is truncated,
when it is concatenated to `buf'.

     const char somestring[] = "bar";
     char buf[5] = "foo";

     if (strlcat(buf, somestring, sizeof(buf)) >= sizeof(buf))
       puts("somestring was truncated, when concatenating to buf.");


File: libc.info,  Node: strlcpy,  Next: strlen,  Prev: strlcat,  Up: Alphabetical List

strlcpy
=======

Syntax
------

     #include <string.h>

     size_t strlcpy (char *dest, const char *src, size_t size);

Description
-----------

Copy characters from SRC to DEST and nul-terminate the resulting
string.  Up to `SIZE - 1' characters are copied to DEST.

SIZE should be the size of the destination string buffer DEST plus the
space for the nul-terminator.  SIZE may be computed in many cases using
the `sizeof' operator.

`strlcpy' is a less ambiguous version of `strncpy' (*note strncpy::).
Unlike `strncpy', `strlcpy' _always_ nul-terminates the destination
DEST for non-zero sizes SIZE.  `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 DEST and 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 `strlcpy' and `strlcat' (*note
strlcat::) is available on the web:
`http://www.openbsd.org/papers/strlcpy-paper.ps'.

Return Value
------------

The length of the string that `strlcpy' tried to create is returned,
whether or not `strlcpy' could store it in DEST.  If all of SRC was
copied, the return value will be less than SIZE.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `somestring' is truncated to fit into `buf'.

     const char somestring[] = "foo";
     char buf[3];

     if (strlcpy(buf, somestring, sizeof(buf)) >= sizeof(buf))
       puts("somestring was truncated, when copying to buf.");


File: libc.info,  Node: strlen,  Next: strlwr,  Prev: strlcpy,  Up: Alphabetical List

strlen
======

Syntax
------

     #include <string.h>

     size_t strlen(const char *string);

Description
-----------

This function returns the number of characters in STRING.

Return Value
------------

The length of the string.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     if (strlen(fname) > PATH_MAX)
       invalid_file(fname);


File: libc.info,  Node: strlwr,  Next: strncasecmp,  Prev: strlen,  Up: Alphabetical List

strlwr
======

Syntax
------

     #include <string.h>

     char *strlwr(char *string);

Description
-----------

This function replaces all upper case letters in STRING with lower case
letters.

Return Value
------------

The string.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     char buf[100] = "Hello";
     strlwr(buf);


File: libc.info,  Node: strncasecmp,  Next: strncat,  Prev: strlwr,  Up: Alphabetical List

strncasecmp
===========

Syntax
------

     #include <string.h>

     int strncasecmp(const char *s1, const char *s2, size_t max);

Description
-----------

This function compares S1 and S2, ignoring case, up to a maximum of MAX
characters.

Return Value
------------

Zero if the strings are equal, a positive number if S1 comes after S2
in the ASCII collating sequense, else a negative number.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     if (strncasecmp(foo, "-i", 2) == 0)
       do_include();


File: libc.info,  Node: strncat,  Next: strncmp,  Prev: strncasecmp,  Up: Alphabetical List

strncat
=======

Syntax
------

     #include <string.h>

     char *strncat(char *s1, const char *s2, size_t max);

Description
-----------

This function concatenates up to MAX characters of S2 to the end of S1.

Return Value
------------

S1

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     strncat(fname, extension, 4);


File: libc.info,  Node: strncmp,  Next: strncpy,  Prev: strncat,  Up: Alphabetical List

strncmp
=======

Syntax
------

     #include <string.h>

     int strncmp(const char *s1, const char *s2, size_t max);

Description
-----------

This function compares up to MAX characters of S1 and S2.

Return Value
------------

Zero if the strings are equal, a positive number if S1 comes after S2
in the ASCII collating sequence, else a negative number.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     if (strncmp(arg, "-i", 2) == 0)
       do_include();


File: libc.info,  Node: strncpy,  Next: strndup,  Prev: strncmp,  Up: Alphabetical List

strncpy
=======

Syntax
------

     #include <string.h>

     char *strncpy(char *s1, const char *s2, size_t max);

Description
-----------

This function copies up to MAX characters of S2 into S1.

Return Value
------------

S1

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     char buf[100];
     strncpy(buf, arg, 99);


File: libc.info,  Node: strndup,  Next: strnicmp,  Prev: strncpy,  Up: Alphabetical List

strndup
=======

Syntax
------

     #include <string.h>

     char * strndup (const char *source, size_t size);

Description
-----------

Returns a newly allocated area of memory that contains a duplicate of
at most SIZE of characters of the string pointed to by SOURCE.  The
memory returned by this call must be freed by the caller.

Return Value
------------

Returns the newly allocated string, or NULL if there is no more memory.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     char *foo()
     {
       return strndup("hello world", 5);
     }


File: libc.info,  Node: strnicmp,  Next: strnlen,  Prev: strndup,  Up: Alphabetical List

strnicmp
========

Syntax
------

     #include <string.h>

     int strnicmp(const char *s1, const char *s2, size_t max);

Description
-----------

This function compares S1 and S2, ignoring case, up to a maximum of MAX
characters.

Return Value
------------

Zero if the strings are equal, a positive number if S1 comes after S2
in the ASCII collating sequence, else a negative number.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     if (strnicmp(foo, "-i", 2) == 0)
       do_include();


File: libc.info,  Node: strnlen,  Next: strpbrk,  Prev: strnicmp,  Up: Alphabetical List

strnlen
=======

Syntax
------

     #include <string.h>

     size_t strnlen(const char *string, size_t size);

Description
-----------

This function returns the number of characters in STRING, but at most
SIZE.  In doing this, the function looks only at the first SIZE
characters at STRING and never beyond STRING + SIZE.

Return Value
------------

The length of the string.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     size_t max_string_length = 10000;

     if (strnlen(fname, max_string_length) > PATH_MAX)
       invalid_file(fname);


File: libc.info,  Node: strpbrk,  Next: strrchr,  Prev: strnlen,  Up: Alphabetical List

strpbrk
=======

Syntax
------

     #include <string.h>

     char *strpbrk(const char *s1, const char *set);

Description
-----------

This function finds the first character in S1 that matches any
character in SET.

Return Value
------------

A pointer to the first match, or `NULL' if none are found.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     if (strpbrk(command, "<>|"))
       do_redirection();


File: libc.info,  Node: strrchr,  Next: strsep,  Prev: strpbrk,  Up: Alphabetical List

strrchr
=======

Syntax
------

     #include <string.h>

     char *strrchr(const char *s1, int c);

Description
-----------

This function finds the last occurrence of `c' in `s1'.

Return Value
------------

A pointer to the last match, or `NULL' if the character isn't in the
string.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     char *last_slash = strrchr(filename, '/');


File: libc.info,  Node: strsep,  Next: strspn,  Prev: strrchr,  Up: Alphabetical List

strsep
======

Syntax
------

     #include <string.h>

     char *strsep(char **stringp, char *delim);

Description
-----------

This function retrieves the next token from the given string, where
STRINGP points to a variable holding, initially, the start of the
string.  Tokens are delimited by a character from DELIM.  Each time the
function is called, it returns a pointer to the next token, and sets
*STRINGP to the next spot to check, or `NULL'.

Return Value
------------

The next token, or NULL.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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'


File: libc.info,  Node: strspn,  Next: strstr,  Prev: strsep,  Up: Alphabetical List

strspn
======

Syntax
------

     #include <string.h>

     size_t strspn(const char *s1, const char *set);

Description
-----------

This function finds the first character in S1 that does not match any
character in SET.  Note that the `NULL' bytes at the end of S1 counts,
so you'll at least get a pointer to the end of the string if nothing
else.

Return Value
------------

The index of the found character.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     int i = strspn(entry, " \t\b");
     if (entry[i])
       do_something();


File: libc.info,  Node: strstr,  Next: strtod,  Prev: strspn,  Up: Alphabetical List

strstr
======

Syntax
------

     #include <string.h>

     char *strstr(const char *s1, const char *s2);

Description
-----------

This function finds the first occurrence of S2 in S1.

Return Value
------------

A pointer within S1, or `NULL' if S2 wasn't found.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     if (strstr(command, ".exe"))
       do_exe();


File: libc.info,  Node: strtod,  Next: strtof,  Prev: strstr,  Up: Alphabetical List

strtod
======

Syntax
------

     #include <stdlib.h>

     double strtod(const char *s, char **endp);

Description
-----------

This function converts as many characters of 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(OPTIONAL
DECIMAL-NUMBER)", "NaN(OPTIONAL OCTAL-NUMBER)" and "NaN(OPTIONAL
HEX-NUMBER)".  If ENDP is not a null pointer, a pointer to the first
unconverted character will be stored in the location pointed to by ENDP.

Return Value
------------

The value represented by S.

If S is "Inf" or "Infinity", with any variations of case and optionally
prefixed with "+" or "-", the return value is `INFINITY' (if no prefix
or a "+" prefix) or `-INFINITY' (if the prefix is "-").

If S is "NaN" or "NaN()", with any variations of case and optionally
prefixed with "+" or "-", the return value is `(double)NAN'.  If the
prefix is "-" the sign bit in the NaN will be set to 1.

If S is "NaN(DECIMAL-NUMBER)", "NaN(OCTAL-NUMBER)" or
"NaN(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 DECIMAL-NUMBER, OCTAL-NUMBER or HEX-NUMBER (the
mantissa for doubles consists of 52 bits).  Use at most 16 hexadecimal
digits in 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) `(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 S doesn't fit into the range of values
representable by the type `double', the function returns either
`-HUGE_VAL' (if S begins with the character `-') or `+HUGE_VAL', and
sets `errno' to `ERANGE'.

Portability
-----------

ANSI/ISO C   C89; C99 (see note 1)
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Notes:

  1. Support for "Inf", "Infinity", "NaN" and "NaN(...)" was
     standardised in ANSI C99.


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);


File: libc.info,  Node: strtof,  Next: strtoimax,  Prev: strtod,  Up: Alphabetical List

strtof
======

Syntax
------

     #include <stdlib.h>

     float strtof(const char *s, char **endp);

Description
-----------

This function converts as many characters of 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(OPTIONAL
DECIMAL-NUMBER)", "NaN(OPTIONAL OCTAL-NUMBER)" and "NaN(OPTIONAL
HEX-NUMBER)".  If ENDP is not a null pointer, a pointer to the first
unconverted character will be stored in the location pointed to by ENDP.

Return Value
------------

The value represented by S.

If S is "Inf" or "Infinity", with any variations of case and optionally
prefixed with "+" or "-", the return value is `INFINITY' (if no prefix
or a "+" prefix) or `-INFINITY' (if the prefix is "-").

If S is "NaN" or "NaN()", with any variations of case and optionally
prefixed with "+" or "-", the return value is `NAN'.  If the prefix is
"-" the sign bit in the NaN will be set to 1.

If S is "NaN(DECIMAL-NUMBER)", "NaN(OCTAL-NUMBER)" or
"NaN(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 DECIMAL-NUMBER, OCTAL-NUMBER or HEX-NUMBER (the
mantissa for floats consists of 23 bits).  Use at most 8 hexadecimal
digits in 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) `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 S doesn't fit into the range of values
representable by the type `float', the function returns either
`-HUGE_VALF' (if S begins with the character `-') or `+HUGE_VALF', and
sets `errno' to `ERANGE'.

Portability
-----------

ANSI/ISO C   C99 (see note 1); not C89
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992

Notes:

  1. Support for "Inf", "Infinity", "NaN" and "NaN(...)" was
     standardised in ANSI C99.


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);


File: libc.info,  Node: strtoimax,  Next: strtok,  Prev: strtof,  Up: Alphabetical List

strtoimax
=========

Syntax
------

     #include <inttypes.h>

     intmax_t strtoimax (const char *s, char **endp, int base)

Description
-----------

This function converts as much of S as looks like an appropriate number
into the value of that number, and sets *ENDP to point to the first
unused character.

The BASE argument indicates what base the digits (or letters) should be
treated as.  If BASE is zero, the base is determined by looking for
`0x', `0X', or `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.

Return Value
------------

The value.

Portability
-----------

ANSI/ISO C   C99; not C89
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992

Example
-------

     printf("Enter a number: "); fflush(stdout);
     gets(buf);
     char *bp;
     printf("The value is %" PRIdMAX "\n", strtoimax(buf, &bp, 0));


File: libc.info,  Node: strtok,  Next: strtok_r,  Prev: strtoimax,  Up: Alphabetical List

strtok
======

Syntax
------

     #include <string.h>

     char *strtok(char *s1, const char *s2);

Description
-----------

This function retrieves tokens from S1 which are delimited by
characters from S2.

To initiate the search, pass the string to be searched as S1.  For the
remaining tokens, pass `NULL' instead.

Return Value
------------

A pointer to the token, or `NULL' if no more are found.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

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'


File: libc.info,  Node: strtok_r,  Next: strtol,  Prev: strtok,  Up: Alphabetical List

strtok_r
========

Syntax
------

     #include <string.h>

     char *strtok_r(char *s1, const char *s2, char **s3);

Description
-----------

This function retrieves tokens from S1 which are delimited by
characters from S2.  It uses S3 to track how far in S1 the search has
progressed.

To initiate the search, pass the string to be searched as S1.  For the
remaining tokens, pass `NULL' instead.

Return Value
------------

A pointer to the token, or `NULL' if no more are found.

Portability
-----------

POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

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'


File: libc.info,  Node: strtol,  Next: strtold,  Prev: strtok_r,  Up: Alphabetical List

strtol
======

Syntax
------

     #include <stdlib.h>

     long strtol(const char *s, char **endp, int base);

Description
-----------

This function converts as much of S as looks like an appropriate number
into the value of that number.  If ENDP is not a null pointer, *ENDP is
set to point to the first unused character.

The BASE argument indicates what base the digits (or letters) should be
treated as.  If BASE is zero, the base is determined by looking for
`0x', `0X', or `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.

Return Value
------------

The value.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     printf("Enter a number: "); fflush(stdout);
     gets(buf);
     char *bp;
     printf("The value is %d\n", strtol(buf, &bp, 0));


File: libc.info,  Node: strtold,  Next: _strtold,  Prev: strtol,  Up: Alphabetical List

strtold
=======

Syntax
------

     #include <stdlib.h>

     long double strtold(const char *s, char **endp);

Description
-----------

This function converts as many characters of 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(OPTIONAL
DECIMAL-NUMBER)", "NaN(OPTIONAL OCTAL-NUMBER)" and "NaN(OPTIONAL
HEX-NUMBER)".  If ENDP is not a null pointer, a pointer to the first
unconverted character will be stored in the location pointed to by ENDP.

Return Value
------------

The value represented by S.

If S is "Inf" or "Infinity", with any variations of case and optionally
prefixed with "+" or "-", the return value is `INFINITY' (if no prefix
or a "+" prefix) or `-INFINITY' (if the prefix is "-").

If S is "NaN" or "NaN()", with any variations of case and optionally
prefixed with "+" or "-", the return value is `(long double)NAN'.  If
the prefix is "-" the sign bit in the NaN will be set to 1.

If S is "NaN(DECIMAL-NUMBER)", "NaN(OCTAL-NUMBER)" or
"NaN(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 DECIMAL-NUMBER, OCTAL-NUMBER or 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 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) `(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).

Portability
-----------

ANSI/ISO C   C99 (see note 1); not C89
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992

Notes:

  1. Support for "Inf", "Infinity", "NaN" and "NaN(...)" was
     standardised in ANSI C99.


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);


File: libc.info,  Node: _strtold,  Next: strtoll,  Prev: strtold,  Up: Alphabetical List

_strtold
========

Syntax
------

     #include <stdlib.h>

     long double _strtold(const char *s, char **endp);

Description
-----------

This function converts as many characters of 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(OPTIONAL
DECIMAL-NUMBER)", "NaN(OPTIONAL OCTAL-NUMBER)" and "NaN(OPTIONAL
HEX-NUMBER)".  If ENDP is not a null pointer, a pointer to the first
unconverted character will be stored in the location pointed to by ENDP.

There is also a standardised version of this function: `strtold' (*note
strtold::).

Return Value
------------

The value represented by S.

If S is "Inf" or "Infinity", with any variations of case and optionally
prefixed with "+" or "-", the return value is `INFINITY' (if no prefix
or a "+" prefix) or `-INFINITY' (if the prefix is "-").

If S is "NaN" or "NaN()", with any variations of case and optionally
prefixed with "+" or "-", the return value is `(long double)NAN'.  If
the prefix is "-" the sign bit in the NaN will be set to 1.

If S is "NaN(DECIMAL-NUMBER)", "NaN(OCTAL-NUMBER)" or
"NaN(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 DECIMAL-NUMBER, OCTAL-NUMBER or 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 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) `(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).

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: strtoll,  Next: strtoul,  Prev: _strtold,  Up: Alphabetical List

strtoll
=======

Syntax
------

     #include <stdlib.h>

     long long int strtoll(const char *s, char **endp, int base);

Description
-----------

This function converts as much of S as looks like an appropriate number
into the value of that number, and sets *ENDP to point to the first
unused character.

The BASE argument indicates what base the digits (or letters) should be
treated as.  If BASE is zero, the base is determined by looking for
`0x', `0X', or `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.

Return Value
------------

The value.

Portability
-----------

ANSI/ISO C   C99; not C89
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992

Example
-------

     printf("Enter a number: "); fflush(stdout);
     gets(buf);
     char *bp;
     printf("The value is %lld\n", strtoll(buf, &bp, 0));


File: libc.info,  Node: strtoul,  Next: strtoull,  Prev: strtoll,  Up: Alphabetical List

strtoul
=======

Syntax
------

     #include <stdlib.h>

     unsigned long strtoul(const char *s, char **endp, int base);

Description
-----------

This is just like `strtol' (*note strtol::) except that the result is
unsigned.

Return Value
------------

The value.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     printf("Enter a number: "); fflush(stdout);
     gets(buf);
     char *bp;
     printf("The value is %u\n", strtoul(buf, &bp, 0));


File: libc.info,  Node: strtoull,  Next: strtoumax,  Prev: strtoul,  Up: Alphabetical List

strtoull
========

Syntax
------

     #include <stdlib.h>

     unsigned long long int strtoull(const char *s, char **endp, int base);

Description
-----------

This is just like `strtoll' (*note strtoll::) except that the result is
unsigned.

Return Value
------------

The value.

Portability
-----------

ANSI/ISO C   C99; not C89
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992

Example
-------

     printf("Enter a number: "); fflush(stdout);
     gets(buf);
     char *bp;
     printf("The value is %llu\n", strtoull(buf, &bp, 0));


File: libc.info,  Node: strtoumax,  Next: strupr,  Prev: strtoull,  Up: Alphabetical List

strtoumax
=========

Syntax
------

     #include <inttypes.h>

     uintmax_t strtoumax (const char *s, char **endp, int base);

Description
-----------

This is just like `strtoimax' (*note strtoimax::) except that the
result is unsigned.

Return Value
------------

The value.

Portability
-----------

ANSI/ISO C   C99; not C89
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992

Example
-------

     printf("Enter a number: "); fflush(stdout);
     gets(buf);
     char *bp;
     printf("The value is %" PRIuMAX "\n", strtoumax(buf, &bp, 0));


File: libc.info,  Node: strupr,  Next: strxfrm,  Prev: strtoumax,  Up: Alphabetical List

strupr
======

Syntax
------

     #include <string.h>

     char *strupr(char *string);

Description
-----------

This function converts all lower case characters in STRING to upper
case.

Return Value
------------

STRING

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     char buf[] = "Foo!";
     strupr(buf);


File: libc.info,  Node: strxfrm,  Next: swab,  Prev: strupr,  Up: Alphabetical List

strxfrm
=======

Syntax
------

     #include <string.h>

     size_t strxfrm(char *s1, const char *s2, size_t max);

Description
-----------

This copies characters from S2 to S1, which must be able to hold MAX
characters.  Each character is transformed according to the locale such
that `strcmp(s1b, s2b)' is just like `strcoll(s1, s2)' where `s1b' and
`s2b' are the transforms of `s1' and `s2'.

Return Value
------------

The actual number of bytes required to transform S2, including the
`NULL'.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: swab,  Next: symlink,  Prev: strxfrm,  Up: Alphabetical List

swab
====

Syntax
------

     #include <stdlib.h>

     void swab(const void *from, void *to, int nbytes);

Description
-----------

This function copies NBYTES bytes from the address pointed to by FROM
to the address pointed by TO, exchanging adjacent even and odd bytes.
It is useful for carrying binary data between little-endian and
big-endian machines.  The argument NBYTES should be even, and the
buffers FROM and TO should not overlap.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: symlink,  Next: syms_init,  Prev: swab,  Up: Alphabetical List

symlink
=======

Syntax
------

     #include <unistd.h>

     int symlink(const char *exists, const char *new);

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.

Return Value
------------

Zero in case of success, -1 in case of failure (and `errno' set to the
appropriate error code).

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     symlink ("c:/djgpp/bin/grep", "c:/djgpp/bin/fgrep");


File: libc.info,  Node: syms_init,  Next: syms_line2val,  Prev: symlink,  Up: Alphabetical List

syms_init
=========

Syntax
------

     #include <debug/syms.h>

     void syms_init (char *file);

Description
-----------

This function reads debugging symbols from the named FILE, which should
be an executable program (either a `.exe' file or a raw COFF image
created by `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 `syms_val2name', `syms_val2line', etc.

You *must* call `syms_init' before calling the other `syms_*' functions.

Currently, `syms_init' only supports COFF and AOUT debugging format, so
programs compiled with `-gstabs' cannot be processed by it.

Return Value
------------

None.

ANSI/ISO C   No
POSIX        No

Example
-------

       syms_init("c:/foo/bar/baz.exe");


File: libc.info,  Node: syms_line2val,  Next: syms_listwild,  Prev: syms_init,  Up: Alphabetical List

syms_line2val
=============

Syntax
------

     #include <debug/syms.h>

     unsigned long syms_line2val (char *filename, int lnum);

Description
-----------

This function returns the address of the first instruction produced from
the line LNUM of the source file FILENAME that was linked into a
program whose symbols were read by a previous call to `syms_init'.

COFF debugging format does not support pathnames, so FILENAME should
not include leading directories, just the basename.

You must call `syms_init' (*note syms_init::) before calling any of the
other `syms_*' functions for the first time.

Return Value
------------

The address of the first instruction produced from the line, or zero if
FILENAME is not found in the symbol table or if no executable code was
generated for line LNUM in FILENAME.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

      syms_init ("foo.exe");
      printf ("Line 3 of foo.c is at address %lx\n",
               syms_line2val("foo.c", 3));


File: libc.info,  Node: syms_listwild,  Next: syms_module,  Prev: syms_line2val,  Up: Alphabetical List

syms_listwild
=============

Syntax
------

     #include <debug/syms.h>

     void syms_listwild (char *pattern,
                         void (*handler) (unsigned long addr, char type_c,
                                          char *name, char *file, int lnum));

Description
-----------

This function walks through all the symbols that were read by a previous
call to `syms_init' (*note syms_init::).  For each symbol whose name
matches PATTERN, it invokes the user-defined function HANDLER, passing
it information about that symbol:

`address'
     the address of the symbol.

`type_c'
     a letter that specifies the type of the symbol, as follows:

    `T'
    `t'
          "text", or code: usually a function.

    `D'
    `d'
          data: an initialized variable.

    `B'
    `b'
          "bss": an uninitialized variable.

    `F'

    `f'
          a function (in `a.out' file only).

    `V'
    `v'
          a set element or pointer (in `a.out' file only).

    `I'
    `i'
          an indirect symbol (in `a.out' file only).

    `U'
    `u'
          an undefined (a.k.a. unresolved) symbol.

    `A'
    `a'
          an absolute symbol.

`name'
     the name of the symbol.

`file'
     the source file name where the symbol is defined.

`lnum'
     the line number on which the symbol is defined in the source file.

Since variables and functions defined in C get prepended with an
underscore `_', begin PATTERN with `_' if you want it to match C
symbols.

You must call `syms_init' (*note syms_init::) before calling any of the
other `syms_*' functions for the first time.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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;
       }


File: libc.info,  Node: syms_module,  Next: syms_name2val,  Prev: syms_listwild,  Up: Alphabetical List

syms_module
===========

Syntax
------

     #include <debug/syms.h>

     char *syms_module (int nfile);

Description
-----------

This function returns the name of the source file (a.k.a. module) whose
ordinal number in the symbol table is NFILE.

You must call `syms_init' (*note syms_init::) before calling any of the
other `syms_*' functions for the first time.

Return Value
------------

The name of the source file, or a `NULL' pointer if NFILE is negative
or larger than the total number of modules linked into the program
whose symbols were read by `syms_init'.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: syms_name2val,  Next: syms_val2line,  Prev: syms_module,  Up: Alphabetical List

syms_name2val
=============

Syntax
------

     #include <debug/syms.h>
     extern int undefined_symbol;
     extern int syms_printwhy;

     unsigned long syms_name2val (const char *string);

Description
-----------

This function returns the address of a symbol specified by STRING.
STRING may be one of the following:

   * A number, with or without a sign, in which case the number
     specifies the address or an offset from an address.

   * A file name and a line number: `FILE#[LINE]', where FILE is the
     name of one of the source files linked into the program whose
     symbols were read by `syms_init', and LINE is a line number in
     that FILE.  If 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 FILE with leading
     directories.

   * A symbol name as a string.  The name can be specified either with
     or without the leading underscore `_'.

   * A register name `%REG'.  REG specifies the value of one of the
     debuggee's registers saved in the external variable `a_tss' (*note
     run_child::).

   * Any sensible combination of the above elements, see the example
     below.

`syms_name2val' looks up the specified file, line, and symbol in the
symbol table prepared by `syms_init', finds their addresses, adds the
offset, if any, and returns the result.

If the specified file, line, or symbol cannot be found, `syms_name2val'
returns zero and sets the global variable `undefined_symbol' to a
non-zero value.  If the global variable `syms_printwhy' is non-zero, an
error message is printed telling which part of the argument STRING was
invalid.

You must call `syms_init' (*note syms_init::) before calling any of the
other `syms_*' functions for the first time.

Return Value
------------

The address specified by STRING, or zero, if none found.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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");


File: libc.info,  Node: syms_val2line,  Next: syms_val2name,  Prev: syms_name2val,  Up: Alphabetical List

syms_val2line
=============

Syntax
------

     #include <debug/syms.h>

     char *syms_val2line (unsigned long addr, int *line, int exact);

Description
-----------

This function takes an address 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 LINE.  If EXACT is non-zero, the
function succeeds only if ADDR is the first address which corresponds
to some source line.

You must call `syms_init' (*note syms_init::) before calling any of the
other `syms_*' functions for the first time.

Return Value
------------

The name of the source file which corresponds to ADDR, or `NULL' if
none was found.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: syms_val2name,  Next: sync,  Prev: syms_val2line,  Up: Alphabetical List

syms_val2name
=============

Syntax
------

     #include <debug/syms.h>

     char *syms_val2name (unsigned long addr, unsigned long *offset);

Description
-----------

This function takes an address ADDR and returns the name of the closest
symbol whose address is less that ADDR.  If OFFSET is not a `NULL'
pointer, the offset of ADDR from the symbol's address is stored in the
variable pointed to by OFFSET.

You must call `syms_init' (*note syms_init::) before calling any of the
other `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 `symify' does
with the call frame traceback.

The function ignores several dummy symbols, like `_end' and `_etext'.

Return Value
------------

The name of the found symbol, or the printed hexadecimal representation
of ADDR, if no symbol was found near ADDR.  The return value is a
pointer to a static buffer, so don't overwrite it and don't pass it to
`free'!

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: sync,  Next: sys_errlist,  Prev: syms_val2name,  Up: Alphabetical List

sync
====

Syntax
------

     #include <unistd.h>

     int sync(void);

Description
-----------

Intended to assist porting Unix programs.  Under Unix, `sync' flushes
all caches of previously written data.  In this implementation, `sync'
calls `fsync' on every open file.  *Note fsync::.  It also calls
`_flush_disk_cache' (*note _flush_disk_cache::) to try to force cached
data to the disk.

Return Value
------------

Always returns 0.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     sync();


File: libc.info,  Node: sys_errlist,  Next: sys_nerr,  Prev: sync,  Up: Alphabetical List

sys_errlist
===========

Syntax
------

     #include <errno.h>

     extern char *sys_errlist[];

Description
-----------

This array contains error messages, indexed by `errno', that describe
the errors.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     printf("Error: %s\n", sys_errlist[errno]);


File: libc.info,  Node: sys_nerr,  Next: sysconf,  Prev: sys_errlist,  Up: Alphabetical List

sys_nerr
========

Syntax
------

     #include <errno.h>

     extern int sys_nerr;

Description
-----------

This variable gives the number of error messages in `sys_errlist'
(*note sys_errlist::).

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     if (errno < sys_nerr)
       printf("Error: %s\n", sys_errlist[errno]);


File: libc.info,  Node: sysconf,  Next: _sysmalloc,  Prev: sys_nerr,  Up: Alphabetical List

sysconf
=======

Syntax
------

     #include <unistd.h>

     long sysconf(int which);

Description
-----------

This function returns various system configuration values, based on
WHICH:

       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;

Return Value
------------

The value.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: _sysmalloc,  Next: system,  Prev: sysconf,  Up: Alphabetical List

_sysmalloc
==========

Syntax
------

     #include <stdlib.h>
     #include <malldbg.h>  /* on non-DJGPP systems */
     #include <sysquery.h> /* alternative on non-DJGPP systems */

     struct _sysquery _sysmalloc(void);

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.

Return Value
------------

A `struct _sysquery', described as follows:

     struct _sysquery {
       unsigned char data, gdlo, sz, prvf, nxtf, nxt, prv, ohead;
       void         *nilp;
       void         *anchors;
       set_m_hook    hookset;
     };

Any unsigned char field set to 255 signifies the value is meaningless.
The `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 `data' is the offset between the
internal pointer and the user pointers.  `nxt' and `prv' link all
allocated memory blocks, while `nxtf' and `prvf' are used only to link
free blocks. `sz' is the internal size of the block, not the user size,
and is normally rounded upward.  Thus the `nxt' field is redundant to
the `sz' field (except when no `nxt' exists) and is used in validity
checking. A `NULL' value in `nxtf' field signifies that the block is
not free. The special value `nilp' is used in `nxtf' and `prvf' as a
`NULL' value distinguishable from `NULL'.

`anchors' points to a `NULL' terminated list of sets of chains of
memory blocks.  These were allocated by `sbrk' and were not contiguous
to any previous allocations.

`hookset' is a pointer to a function that can set malloc hooks, as
described in `mallsethook'.  It is only available through this link.

Portability
-----------

ANSI/ISO C   No
POSIX        No

This function is specific to DJGPP.

Example
-------

     struct _sysquery sysinfo = _sysmalloc();


File: libc.info,  Node: system,  Next: tan,  Prev: _sysmalloc,  Up: Alphabetical List

system
======

Syntax
------

     #include <stdlib.h>

     int system(const char *cmd);

Description
-----------

This function runs the command or program specified by CMD.  If CMD is
a null pointer, `system' returns non-zero only if a shell is available.
If CMD is an empty string, the command processor pointed to by `SHELL'
or `COMSPEC' variables in the environment will be invoked
interactively; type `exit <RET>' to return to the program which called
`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
`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 `PE-COFF' format), or when the system shell
is `4DOS' or `NDOS', command lines longer than 126 characters are
passed via the environment variable `CMDLINE'.

Command lines and pipes (i.e., the use of `<', `>', `>>', and `|') 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, `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
`COMMAND.COM' always exits with code 0.

Certain commands internal to `COMMAND.COM' that don't make sense or
cause no effect in the context of `system' are ignored by this
function.  These are `REM', `EXIT', `GOTO', `SHIFT'; `SET', `PATH' and
`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 `system', because the
emulation is better than the original.  Currently, the only emulated
command is `CD' or `CHDIR': the emulation knows about forward slashes
and also switches the current drive.  This emulation can also be
switched off, as explained below.

When `system' is presented with an internal shell command, it checks
the environment variables `SHELL' and `COMSPEC' (in that order) and
invokes the program that they point to.  If the shell thus found is one
of the DOS shells (`COMMAND.COM', `4DOS' or `NDOS'), they are called
with the `/c' switch prepended to the command line.  Otherwise,
`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 `#! /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, `system' will additionally search for it
on the `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 `system' using a bit-mapped variable
`__system_flags', defined on `<stdlib.h>'.  The following bits are
currently defined:

`__system_redirect'
     When set (the default), specifies that `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.

`__system_call_cmdproc'
     When set, `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 _always_ set this bit if you use a real, Unix-style
     shell (also, set `__system_use_shell', described below, and the
     `SHELL' environment variable).

`__system_use_shell'
     When set (the default), the `SHELL' environment variable will take
     precedence upon `COMSPEC'; this allows you to specify a special
     shell for `system' that doesn't affect the rest of DOS.  If reset,
     only `COMSPEC' is used to find the name of the command processor.

`__system_allow_multiple_cmds'
     When set, you can put multiple commands together separated by the
     `;' character.  If reset (the default), the command line passed to
     `system' is executed as a single command and `;' has no special
     meaning.

`__system_allow_long_cmds'
     When set (the default), `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,
     `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.

`__system_emulate_command'
     If reset (the default), `system' will pass the entire command line
     to the shell if its name is one of the following: `sh.exe',
     `sh16.exe', `sh32.exe', `bash.exe', `tcsh.exe'.  When set,
     `system' will attempt to emulate redirection and pipes internally,
     even if `COMSPEC' or `SHELL' point to a Unix-style shell.

`__system_handle_null_commands'
     When set (the default), commands internal to `COMMAND.COM' and
     compatible shells which have no effect in the context of `system',
     are ignored (the list of these commands was given above).  If
     reset, these commands are processed as all others, which means
     `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 `__system_call_cmdproc' bit which will
     always call the shell.

`__system_ignore_chdir'
     If set, the `CD' and `CHDIR' commands are ignored.  When reset
     (the default), the processing of these commands depends on the
     `__system_emulate_chdir' bit, see below.

     This bit is for compatibility with Unix, where a single `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 `__system_allow_multiple_cmds' above).

`__system_emulate_chdir'
     When set, the `CD' and `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 `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), `CD' and `CHDIR'
     are passed to the shell.

The behavior of `system' can be customized at run time by defining the
variable `DJSYSFLAGS' in the environment.  The value of that variable
should be the numerical value of `__system_flags' that you'd like to
set; it will override the value of `__system_flags' specified when the
program was compiled.

Return Value
------------

If CMD is a null pointer, `system' returns non-zero if a shell is
available.  The actual test for the existence of an executable file
pointed to by `SHELL' or `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 `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 `SIGINT' or
`SIGABRT' if the child process was aborted by `Ctrl-C' or Critical
Device Error, respectively; otherwise they will be zero(1).  If the
child couldn't be run, `system' will return -1 and set `errno' to an
appropriate value.  Note that if `COMMAND.COM' was used to run the
child, it will always return a 0 status, even if the command didn't run
successfully.  However, `system' only calls `COMMAND.COM' when it needs
to run commands internal to it.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     system("cc1plus.exe @cc123456.gp");

---------- Footnotes ----------

(1) Many DOS programs catch `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 `system' will most probably be zero.  Don't
count on these bits to hold the signal number!


File: libc.info,  Node: tan,  Next: tanh,  Prev: system,  Up: Alphabetical List

tan
===

Syntax
------

     #include <math.h>

     double tan(double x);

Description
-----------

This function computes the tangent of X (which should be given in
radians).

Return Value
------------

The tangent of X.  If the absolute value of X is finite but greater
than or equal to 2^63, the return value is 0 (since for arguments that
large each bit of the mantissa is more than `Pi').  If the value of X
is infinite or `NaN', the return value is `NaN' and `errno' is set to
`EDOM'.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: tanh,  Next: tcdrain,  Prev: tan,  Up: Alphabetical List

tanh
====

Syntax
------

     #include <math.h>

     double tanh(double x);

Description
-----------

This function computes the hyperbolic tangent of X.

Return Value
------------

The hyperbolic tangent of X.  If X is either a positive or a negative
infinity, the result is unity with the same sign as X, and `errno' is
not changed.  If X is `NaN', the return value is `NaN' and `errno' is
set to `EDOM'.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: tcdrain,  Next: tcflow,  Prev: tanh,  Up: Alphabetical List

tcdrain
=======

Syntax
------

     #include <termios.h>

     int tcdrain (int fd);

Description
-----------

This function waits until all the output is written to the file/device
referred to by the handle 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.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: tcflow,  Next: tcflush,  Prev: tcdrain,  Up: Alphabetical List

tcflow
======

Syntax
------

     #include <termios.h>

     int tcflow (int fd, int action);

Description
-----------

This function suspends transmission of data to, or reception of data
from, the device/file open on handle FD.  The ACTION argument can take
one of these values:

`TCOOFF'
     the output is suspended

`TCOON'
     the output is resumed

`TCIOFF'
     the STOP character is transmitted

`TCION'
     the START character is transmitted

The current START and STOP characters are stored in the `termios'
structure that is currently in effect.  *Note Termios functions::, for
more details about that.

Note that the DJGPP termios emulation handles console only.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: tcflush,  Next: tcgetattr,  Prev: tcflow,  Up: Alphabetical List

tcflush
=======

Syntax
------

     #include <termios.h>

     int tcflush (int fd, int which);

Description
-----------

This function clears the input and/or output queues on for the
device/file open on handle FD.  The WHICH argument can take these
values:

`TCIFLUSH'
     the unprocessed characters in the input buffer are discarded

`TCOFLUSH'
     no effect (provided for compatibility)

`TCIOFLUSH'
     has the combined effect of `TCIFLUSH' and `TCOFLUSH'

Note that the termios emulation handles console only.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: tcgetattr,  Next: tcgetpgrp,  Prev: tcflush,  Up: Alphabetical List

tcgetattr
=========

Syntax
------

     #include <termios.h>

     int tcgetattr (int fd, struct termios *termiosp);

Description
-----------

This function gets the parameters associated with the file/device
referred to by the handle FD and stores them in the termios structure
TERMIOSP.  *Note Termios functions::, for the full description of
`struct termios' and its members.

Note that the termios emulation handles console only.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     struct termios termiosbuf;
     int rc = tcgetattr (0, &termiosbuf);


File: libc.info,  Node: tcgetpgrp,  Next: tcsendbreak,  Prev: tcgetattr,  Up: Alphabetical List

tcgetpgrp
=========

Syntax
------

     #include <termios.h>

     int tcgetpgrp (int fd);

Description
-----------

This function returns the value of the "process group ID" for the
foreground process associated with the terminal.  The file descriptor
FD must be connected to the terminal, otherwise the function will fail.

Return Value
------------

If FD is connected to the terminal, the function returns the process
group ID, which is currently identical to the value returned by
`getpgrp()' (*note getpgrp::).  Otherwise, it returns -1 and sets
`errno' to `ENOTTY'.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: tcsendbreak,  Next: tcsetattr,  Prev: tcgetpgrp,  Up: Alphabetical List

tcsendbreak
===========

Syntax
------

     #include <termios.h>

     int tcsendbreak (int fd, int duration);

Description
-----------

This function generates a break condition for `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.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: tcsetattr,  Next: tcsetpgrp,  Prev: tcsendbreak,  Up: Alphabetical List

tcsetattr
=========

Syntax
------

     #include <termios.h>

     int tcsetattr (int fd, int action, const struct termios *termiosp);

Description
-----------

This function sets termios structure for device open on the handle FD
from the structure TERMIOSP.  Note that the termios emulation handles
console only.

The ACTION argument can accept the following values:

`TCSANOW'

`TCSADRAIN'

`TCSAFLUSH'

Currently, any of these values causes the values in TERMIOSP to take
effect immediately.

*Note Termios functions::, for the description of the `struct termios'
structure.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     tcsetattr (0, TCSANOW, &termiosbuf);


File: libc.info,  Node: tcsetpgrp,  Next: tell,  Prev: tcsetattr,  Up: Alphabetical List

tcsetpgrp
=========

Syntax
------

     #include <termios.h>

     int tcsetpgrp (int fd, pid_t pgroup_id);

Description
-----------

This function sets the foreground "process group ID" for the terminal
connected to file descriptor FD.  FD must be a valid handle connected
to a terminal device, and PGROUP_ID must be the process group ID of the
calling process, or the function will fail.

Return Value
------------

If FD is a valid handle connected to a terminal and PGROUP_ID is equal
to what `getpgrp()' returns (*note getpgrp::), the function will do
nothing and return zero.  Otherwise, -1 will be returned and `errno'
will be set to a suitable value.  In particular, if the PGROUP_ID
argument is different from what `getpgrp()' returns, `tcsetpgrp' sets
`errno' to `ENOSYS'.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: tell,  Next: telldir,  Prev: tcsetpgrp,  Up: Alphabetical List

tell
====

Syntax
------

     #include <io.h>

     off_t tell(int file);

Description
-----------

This function returns the location of the file pointer for FILE.

Return Value
------------

The file pointer, or -1 on error.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     off_t q = tell(fd);


File: libc.info,  Node: telldir,  Next: tempnam,  Prev: tell,  Up: Alphabetical List

telldir
=======

Syntax
------

     #include <dirent.h>

     long telldir(DIR *dir);

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 `seekdir' (*note seekdir::).

Return Value
------------

The directory pointer.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     DIR *dir;
     long q = telldir(dir);
     do_something();
     seekdir(dir, q);


File: libc.info,  Node: tempnam,  Next: Termios functions,  Prev: telldir,  Up: Alphabetical List

tempnam
=======

Syntax
------

     #include <stdio.h>

     char * tempnam(const char *tmpdir, const char *prefix);

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 TMPDIR
points to the name of the directory in which the temporary file will be
created, `tempnam' will ensure that the generate name is unique *in
that directory*.  If the argument 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 PREFIX will be used.

If TMPDIR is `NULL', or empty, or points to a non-existent directory,
`tempnam' will use a default directory.  The default directory is
determined by testing, in sequence, the directories defined by the
values of environment variables `TMPDIR', `TEMP' and `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, `tempnam' will
use the static default path prefix defined by `P_tmpdir' on
`<stdio.h>', or `"c:/"', in that order.

If PREFIX is `NULL' or empty, `tempnam' will supply its own default
prefix `"tm"'.

`tempnam' puts the generated name into space allocated by `malloc'.  It
is up to the caller to free that space when it is no longer needed.

Note that `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.

Return Value
------------

On success, `tempnam' returns a pointer to space (allocated with a call
to `malloc') where the file name is constructed.  If `malloc' failed to
provide sufficient memory buffer, or if no valid directory to hold the
file was found, `tempnam' returns a `NULL' pointer.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

       #include <stdio.h>

         tempnam ("c:/tmp/", "foo");


File: libc.info,  Node: Termios functions,  Next: textattr,  Prev: tempnam,  Up: Alphabetical List

Termios functions
=================

The `termios' functions allow to control terminals and asynchronous
communications ports.  The DJGPP implementation currently supports the
`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 `termios' functions accept a TERMIOSP argument which is a
pointer to a `struct termios' variable.  Here's the description of this
structure:

      #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 */
      }

The array `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:

Index   Name     Function                    Default
                                             Value
1       VEOF     Signal End-Of-Input         Ctrl-D
2       VEOL     Signal End-Of-Line          [Disabled]
3       VERASE   Delete previous character   Backspace
4       VINTR    Generate SIGINT             Ctrl-C
5       VKILL    Erase current line          Ctrl-U
6       VMIN     The MIN value               1
7       VQUIT    Generate SIGQUIT            Ctrl-\
8       VSTART   Resume output               Ctrl-Q
9       VSTOP    Suspend output              Ctrl-S
10      VSUSP    Suspend program             Ctrl-Z
11      VTIME    TIME value                  0

The special characters (like `VEOL', `VKILL', etc.) produce their
effect only under the "canonical input processing", that is, when the
`ICANON' bit in the `c_lflag' member of `struct termios' (see below) is
set.  If `ICANON' is *not* set, all characters are processed as regular
characters and returned to the caller; only the `VMIN' and `VTIME'
parameters are meaningful in the "non-canonical processing" mode.

The `VEOL' character can be used to signal end of line (and thus end of
input in the canonical mode) in addition to the normal `RET' key.  In
the non-canonical mode, input ends as soon as at least `VMIN'
characters are received.

Note that the values of `VMIN' and `VTIME' are currently ignored;
`termios' functions always work as if `VMIN' were 1 and `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 `c_cflag' member of `struct termios' describes the hardware
terminal control, as follows:

Symbol   Function
B0       Hang up
B50      50 baud
B75      75 baud
B110     110 baud
B134     134.5 baud
B150     150 baud
B200     200 baud
B300     300 baud
B600     600 baud
B1200    1200 baud
B1800    1800 baud
B2400    2400 baud
B4800    4800 baud
B9600    9600 baud
B19200   19200 baud
B38400   38400 baud
CSIZE    Character size:
CS5      5-bit characters
CS6      6-bit characters
CS7      7-bit characters
CS8      8-bit characters
CSTOPB   If set, send two stop bits
CREAD    Enable reading
PARENB   Enable parity
PARODD   If set, use odd parity
HUPCL    Hang up on last close
CLOCAL   If set, line is local

Note that since the DOS terminal doesn't use asynchronous ports, the
above parameters are always ignored by the implementation.  The default
value of `c_cflag' is `(CS8|CREAD|CLOCAL)'.

The `c_lflag' member of `struct termios' defines the local modes that
control the terminal functions:

Symbol   Function
ISIG     If set, enable signals SIGINT and SIGQUIT
ICANON   If set, enable canonical input processing
ECHO     If set, enable echoing
ECHOE    Erase character deletes
ECHOK    Output newline after the kill character
ECHONL   Echo the newline
NOFLSH   [Ignored]
TOSTOP   [Ignored]
ECHOCTL  Echo control characters as ^X
ECHOKE   Erase killed line
IEXTEN   [Ignored]

The default value of `c_lflag' is
`(ISIG|ICANON|ECHO|IEXTEN|ECHOE|ECHOKE|ECHOCTL)'.

The `c_iflag' member of `struct termios' describes the input control:

Symbol   Function
IGNBRK   Ignore Ctrl-BREAK
BRKINT   Generate SIGINT on Ctrl-BREAK
IGNPAR   [Ignored]
PARMRK   [Ignored]
INPCK    [Ignored]
ISTRIP   Strip the 8th bit from input
INLCR    Map NL to CR on input
IGNCR    Ignore CR characters
ICRNL    Map CR to NL on input
IXON     [Ignored]
IXOFF    Enable start/stop input control
IMAXBEL  Ring the bell if input line too long

The default value of `c_iflag' is `(BRKINT|ICRNL|IMAXBEL)'.

The `c_oflag' member of `struct termios' specifies the output handling:

Symbol   Function
OPOST    If not set, output characters
         verbatim
ONLCR    Map newline to CR-LF pair on output
OCRNL    Map CR to NL on output
ONOEOT   Don't output EOT characters

Note that if the `OPOST' bit is not set, all the other flags are
ignored and the characters are output verbatim.  The default value of
`c_oflag' is `(OPOST|ONLCR|ONOEOT)'.

The `c_ispeed' and `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.


File: libc.info,  Node: textattr,  Next: textbackground,  Prev: Termios functions,  Up: Alphabetical List

textattr
========

Syntax
------

     #include <conio.h>

     void textattr(int _attr);

Description
-----------

Sets the attribute used for future writes to the screen:

     ---- XXXX = foreground color
     -XXX ---- = background color
     X--- ---- = 1=blink 0=steady

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.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     /* blinking white on blue */
     textattr(BLINK | (BLUE << 4) | WHITE);

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: textbackground,  Next: textcolor,  Prev: textattr,  Up: Alphabetical List

textbackground
==============

Syntax
------

     #include <conio.h>

     void textbackground(int _color);

Description
-----------

Sets just the background of the text attribute. *Note textattr::.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: textcolor,  Next: textmode,  Prev: textbackground,  Up: Alphabetical List

textcolor
=========

Syntax
------

     #include <conio.h>

     void textcolor(int _color);

Description
-----------

Sets just the foreground of the text attribute. *Note textattr::.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: textmode,  Next: time,  Prev: textcolor,  Up: Alphabetical List

textmode
========

Syntax
------

     #include <conio.h>

     void textmode(int _mode);

Description
-----------

Sets the text mode of the screen.  _MODE is one of the following:

`LASTMODE'
     The text mode which was in effect _before_ the last call to
     `textmode()'.

`BW40'
     40-column black and white (on a color screen)

`C40'
     40-color color.

`BW80'
     80-column black and white (on a color screen)

`C80'
     80-column color

`MONO'
     The monochrome monitor

`C4350'
     80-column, 43- (on EGAs) or 50-row (on VGAs) color


*Note _set_screen_lines::, for a more versatile method of setting text
screen dimensions.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: time,  Next: times,  Prev: textmode,  Up: Alphabetical List

time
====

Syntax
------

     #include <time.h>

     time_t time(time_t *t);

Description
-----------

If T is not `NULL', the current time is stored in `*t'.

Return Value
------------

The current time is returned.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     printf("Time is %d\n", time(0));


File: libc.info,  Node: times,  Next: tmpfile,  Prev: time,  Up: Alphabetical List

times
=====

Syntax
------

     #include <sys/times.h>

     clock_t times(struct tms *buf);

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 `CLOCKS_PER_SEC', defined on time.h.

This is the structure in which `times' returns its info:

     struct  tms {
       clock_t tms_cstime;
       clock_t tms_cutime;
       clock_t tms_stime;
       clock_t tms_utime;
     };

Currently, the elapsed time of the running program is returned in the
`tms_utime' field, and all other fields return as zero.

Return Value
------------

The number of elapsed tics since the program started.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     printf("We used %d seconds of elapsed time\n",
            times(&buf)/CLOCKS_PER_SEC);


File: libc.info,  Node: tmpfile,  Next: tmpnam,  Prev: times,  Up: Alphabetical List

tmpfile
=======

Syntax
------

     #include <stdio.h>

     FILE *tmpfile(void);

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() (*note
tmpnam::).

Return Value
------------

A newly opened file.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     FILE *tmp = tmpfile();


File: libc.info,  Node: tmpnam,  Next: toascii,  Prev: tmpfile,  Up: Alphabetical List

tmpnam
======

Syntax
------

     #include <stdio.h>

     char *tmpnam(char *s);

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 `TMP_MAX' times
(`TMP_MAX' is defined on stdio.h).  If `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 `"TMPDIR"', `"TEMP"' and `"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, `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).

Return Value
------------

If S is a null pointer, `tmpnam' leaves its result in an internal
static buffer and returns a pointer to that buffer.  If S is not a null
pointer, it is assumed to point to an array of at least `L_tmpnam'
characters, and `tmpnam' writes its result in that array and returns a
pointer to it as its value.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     char buf[L_tmpnam];
     char *s = tmpnam(buf);


File: libc.info,  Node: toascii,  Next: _tolower,  Prev: tmpnam,  Up: Alphabetical List

toascii
=======

Syntax
------

     #include <ctype.h>

     int toascii(int c);

Description
-----------

This function strips the high bit of C, forcing it to be an ASCII
character.

Return Value
------------

The ASCII character.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     for (i=0; buf[i]; i++)
       buf[i] = toascii(buf[i]);


File: libc.info,  Node: _tolower,  Next: tolower,  Prev: toascii,  Up: Alphabetical List

_tolower
========

Syntax
------

     #include <ctype.h>

     int _tolower(int c);

Description
-----------

This function returns C, converting it to lower case.  For the reverse,
use `_toupper' (*note _toupper::).

This function is like `tolower' (*note tolower::), except that the
caller should ensure that C is upper case.

Return Value
------------

The lower case letter.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992

Example
-------

     for (i=0; buf[i]; i++)
       buf[i] = _tolower(buf[i]);


File: libc.info,  Node: tolower,  Next: _toupper,  Prev: _tolower,  Up: Alphabetical List

tolower
=======

Syntax
------

     #include <ctype.h>

     int tolower(int c);

Description
-----------

This function returns C, converting it to lower case if it is upper
case.  *Note toupper::.

Return Value
------------

The lower case letter.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     for (i=0; buf[i]; i++)
       buf[i] = tolower(buf[i]);


File: libc.info,  Node: _toupper,  Next: toupper,  Prev: tolower,  Up: Alphabetical List

_toupper
========

Syntax
------

     #include <ctype.h>

     int _toupper(int c);

Description
-----------

This function returns C, converting it to upper case.  For the reverse,
use `_tolower' (*note _tolower::).

This function is like `toupper' (*note toupper::), except that the
caller should ensure that C is lower case.

Return Value
------------

The upper case letter.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992

Example
-------

     for (i=0; buf[i]; i++)
       buf[i] = _toupper(buf[i]);


File: libc.info,  Node: toupper,  Next: _truename,  Prev: _toupper,  Up: Alphabetical List

toupper
=======

Syntax
------

     #include <ctype.h>

     int toupper(int c);

Description
-----------

This function returns C, converting it to upper case if it is lower
case. *Note tolower::.

Return Value
------------

The upper case letter.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     for (i=0; buf[i]; i++)
       buf[i] = toupper(buf[i]);


File: libc.info,  Node: _truename,  Next: _truename_sfn,  Prev: toupper,  Up: Alphabetical List

_truename
=========

Syntax
------

     #include <sys/stat.h>

     char * _truename(const char *path, char *true_path);

Description
-----------

Given a PATH of a file, returns in 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 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 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 TRUE_PATH (see below).

`_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 (`c:\thisis~1' instead of `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 `_truename_sfn' (*note
_truename_sfn::) instead in this case.

Upon success, the function will place the result in TRUE_PATH, if
that's non-NULL; the buffer should be large enough to contain the
largest possible pathname (PATH_MAX characters).  If TRUE_PATH is a
NULL pointer, the space to hold the result will be allocated by calling
`malloc' (*note malloc::); it is up to the caller to release the buffer
by calling `free' (*note free::).

Return Value
------------

The function returns the pointer to the result.  In case of any failure,
a NULL pointer is returned, and `errno' is set.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

       fprintf(stderr,
               "True name of %s is %s\n", path, _truename(path, (char *)0));


File: libc.info,  Node: _truename_sfn,  Next: truncate,  Prev: _truename,  Up: Alphabetical List

_truename_sfn
=============

Syntax
------

     #include <sys/stat.h>

     char * _truename_sfn(const char *path, char *true_path);

Description
-----------

`_truename_sfn' is like `_truename', except that it always returns a
short filename. See the documentation for `_truename' for more details
(*note _truename::).

Return Value
------------

The function returns the pointer to the result.  In case of any failure,
a NULL pointer is returned, and `errno' is set.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

       fprintf(stderr,
               "True short name of %s is %s\n", path,
     	  _truename_sfn(path, (char *)0));


File: libc.info,  Node: truncate,  Next: ttyname,  Prev: _truename_sfn,  Up: Alphabetical List

truncate
========

Syntax
------

     #include <unistd.h>

     int truncate(const char *file, off_t size);

Description
-----------

This function truncates FILE to SIZE bytes.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     truncate("/tmp/data.txt", 400);


File: libc.info,  Node: ttyname,  Next: tzset,  Prev: truncate,  Up: Alphabetical List

ttyname
=======

Syntax
------

     #include <unistd.h>

     char *ttyname(int file);

Description
-----------

Gives the name of the terminal associated with FILE.

Return Value
------------

Returns "con" if FILE is a device, else `NULL'.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     char *tty = ttyname(0);


File: libc.info,  Node: tzset,  Next: tzsetwall,  Prev: ttyname,  Up: Alphabetical List

tzset
=====

Syntax
------

     #include <time.h>

     extern char *tzname[2];
     void tzset(void);

Description
-----------

This function initializes the global variable `tzname' according to
environment variable `TZ'.  After the call, `tzname' holds the
specifications for the time zone for the standard and daylight-saving
times.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: tzsetwall,  Next: uclock,  Prev: tzset,  Up: Alphabetical List

tzsetwall
=========

Syntax
------

     #include <time.h>

     void tzsetwall(void);

Description
-----------

This function sets up the time conversion information used by
`localtime' (*note localtime::) so that `localtime' returns the best
available approximation of the local wall clock time.

Return Value
------------

None.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: uclock,  Next: umask,  Prev: tzsetwall,  Up: Alphabetical List

uclock
======

Syntax
------

     #include <time.h>

     uclock_t uclock(void);

Description
-----------

This function returns the number of uclock ticks since an arbitrary
time, actually, since the first call to `uclock', which itself returns
zero.  The number of tics per second is `UCLOCKS_PER_SEC' (declared in
the `time.h' header file.

`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 `printf' will only print a value of type `uclock_t' correctly
if you use the format specifier for `long long' data, `%lld', because
`uclock_t' is a 64-bit integer.  *Note printf::.

Also note that `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 `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 `uclock' there are incorrect.  DOS and Windows 9X don't have this
problem.

Windows NT, 2000 and XP attempt to use the `rdtsc' feature of newer
CPUs instead of the interval timer, because the timer tick and interval
timer are not coordinated.  During calibration the `SIGILL' signal
handler is replaced to protect against systems which do not support or
allow `rdtsc'.  If `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 `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.

Return Value
------------

The number of tics.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     printf("%lld ticks have elapsed\n", (long long)(uclock()));
     printf("%f second have elapsed\n",
            ((double)uclock()/UCLOCKS_PER_SEC));


File: libc.info,  Node: umask,  Next: uname,  Prev: uclock,  Up: Alphabetical List

umask
=====

Syntax
------

     #include <sys/stat.h>

     mode_t umask(mode_t cmask);

Description
-----------

This function does nothing.  It exists to assist porting.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: uname,  Next: ungetc,  Prev: umask,  Up: Alphabetical List

uname
=====

Syntax
------

     #include <sys/utsname.h>

     int uname(struct utsname *u);

Description
-----------

Fills in the structure with information about the system.

     struct utsname {
       char machine[9];
       char nodename[32];
       char release[9];
       char sysname[9];
       char version[9];
     };

`machine'
     The CPU family type: `"i386"', `"i486"', `"i586"' (Pentium),
     `"i686"' (PentiumPro, Pentium II, Pentium III), or `"i786"'
     (Pentium 4).

`nodename'
     The name of your PC (if networking is installed), else `"pc"'.

`release'
     The major version number of DOS.  For example, DOS 1.23 would
     return `"1"' here.

`sysname'
     The flavor of the OS.

`version'
     The minor version number of DOS.  For example, DOS 1.23 would
     return `"23"' here.

Return Value
------------

Zero on success, else nonzero.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: ungetc,  Next: ungetch,  Prev: uname,  Up: Alphabetical List

ungetc
======

Syntax
------

     #include <stdio.h>

     int ungetc(int c, FILE *file);

Description
-----------

This function pushes C back into the FILE.  You can only push back one
character at a time.

Return Value
------------

The pushed-back character, or `EOF' on error.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     int q;
     while (q = getc(stdin) != 'q');
     ungetc(q);


File: libc.info,  Node: ungetch,  Next: unlink,  Prev: ungetc,  Up: Alphabetical List

ungetch
=======

Syntax
------

     #include <conio.h>

     int ungetch(int);

Description
-----------

Puts a character back, so that `getch' (*note getch::) will return it
instead of actually reading the console.

Return Value
------------

The character is returned.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: unlink,  Next: unlock,  Prev: ungetch,  Up: Alphabetical List

unlink
======

Syntax
------

     #include <unistd.h>

     int unlink(const char *file);

Description
-----------

This function removes a file from the file system.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992 (partial); 1003.1-2001 (partial); 1003.1-2008
             (partial); (see note 1)

Notes:

  1. The 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 `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 POSIX expects.  On Windows 9x and
     Windows ME (and possibly Windows XP as well), the removal will
     simply fail (`errno' gets set to `EACCES').  On DOS, removing an
     open file could lead to filesystem corruption if the removed file
     is written to before it's closed.

Example
-------

     unlink("data.txt");


File: libc.info,  Node: unlock,  Next: unlock64,  Prev: unlink,  Up: Alphabetical List

unlock
======

Syntax
------

     #include <io.h>

     int unlock(int fd, long offset, long length);

Description
-----------

Unlocks a region previously locked by `lock'.

*Note lock::.

Return Value
------------

Zero if successful, nonzero if not.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: unlock64,  Next: unsetenv,  Prev: unlock,  Up: Alphabetical List

unlock64
========

Syntax
------

     #include <io.h>

     int unlock64(int fd, long long offset, long long length);

Description
-----------

Unlocks a region previously locked by `lock64'.

Arguments OFFSET and LENGTH must be of type `long long', thus enabling
you to unlock with offsets and lengths as large as ~2^63 (FAT16 limits
this to ~2^31; FAT32 limits this to 2^32-2).

*Note lock64::.

Return Value
------------

Zero if successful, nonzero if not.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: unsetenv,  Next: _use_lfn,  Prev: unlock64,  Up: Alphabetical List

unsetenv
========

Syntax
------

     #include <stdlib.h>

     int unsetenv(const char *name);

Description
-----------

This function removes the environment variable NAME from the
environment.  This will update the list of pointers to which the
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.

Return Value
------------

If NAME is `NULL', points to an empty string, or points to a string
containing a `=', this function returns -1 and sets `errno' to
`EINVAL'; otherwise it returns 0.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008; (see note 1)

Notes:

  1. This function is new to the Posix 1003.1-200x draft


File: libc.info,  Node: _use_lfn,  Next: usleep,  Prev: unsetenv,  Up: Alphabetical List

_use_lfn
========

Syntax
------

     #include <fcntl.h>

     char _use_lfn(const char *path);

Description
-----------

The `_use_lfn' function returns a nonzero value if the low level libc
routines will use the "Long File Name" (LFN) functions provided with
Windows 9x (and other advanced filesystems), when accessing files and
directories on the same filesystem as PATH.  PATH may be any legal
pathname; however, the function only needs the name of the root
directory on the particular drive in question.  If PATH is a `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 PATH does not specify
the drive explicitly, the current drive is used.

The header `fcntl.h' defines a macro `_USE_LFN'; applications should
use this macro instead of calling `_use_lfn' directly.  That is so this
routine could be replaced with one which always returns 0 to disable
using long file names.  Calling `_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,
`_USE_LFN' assumes that LFN API does _not_ depend on a drive.

Long file names can also be disabled by setting the flag
`_CRT0_FLAG_NO_LFN' in `_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 `LFN' to
`N', i.e. `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 `LFN=n'.  The environment variable can be set in the
`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 `LFN=n' in your `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.

Return Value
------------

If LFN APIs are supported and should be used, it returns 1, else 0.

Note that if the `_CRT0_FLAG_NO_LFN' bit is set, or `LFN' is set to `N'
or `n' in the environment, both `_use_lfn' and `_USE_LFN' will always
return 0 without querying the filesystem.  You can reset the
`_CRT0_FLAG_NO_LFN' bit at runtime to force filesystem to be queried.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------


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

       int fd = creat (_USE_LFN ? "MyCurrentJobFile.Text" : "currjob.txt",
                       S_IRUSR | S_IWUSR);


File: libc.info,  Node: usleep,  Next: utime,  Prev: _use_lfn,  Up: Alphabetical List

usleep
======

Syntax
------

     #include <unistd.h>

     unsigned usleep(unsigned usec);

Description
-----------

This function pauses the program for USEC microseconds.  Note that,
since `usleep' calls `clock' internally, and the latter has a 55-msec
granularity, any argument less than 55msec will result in a pause of
random length between 0 and 55 msec.  Any argument less than 11msec
(more precisely, less than 11264 microseconds), will always result in
zero-length pause (because `clock' multiplies the timer count by 5).
*Note clock::.

Return Value
------------

The number of unslept microseconds (i.e. zero).

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     usleep(500000);


File: libc.info,  Node: utime,  Next: utimes,  Prev: usleep,  Up: Alphabetical List

utime
=====

Syntax
------

     #include <utime.h>

     int utime(const char *file, const struct utimbuf *time);

Description
-----------

This function sets the modification timestamp on the FILE.  The new
time is stored in this structure:

     struct utimbuf
     {
         time_t  actime;  /* access time (unused on FAT filesystems) */
         time_t  modtime; /* modification time */
     };

Note that, as under DOS a file only has a single timestamp, the
`actime' field of `struct utimbuf' is ignored by this function, and
only `modtime' field is used.  On filesystems which support long
filenames, both fields are used and both access and modification times
are set.

If 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.

Return Value
------------

Zero for success, nonzero for failure.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     struct utimbuf t;
     t.modtime = time(0);
     utime("data.txt", &t);


File: libc.info,  Node: utimes,  Next: v2loadimage,  Prev: utime,  Up: Alphabetical List

utimes
======

Syntax
------

     #include <sys/time.h>

     int utimes(const char *file, struct timeval tvp[2]);

Description
-----------

This function sets the file access time as specified by `TVP[0]', and
its modification time as specified by `TVP[1]'.  `struct timeval' is
defined as follows:

     struct timeval {
       time_t tv_sec;
       long tv_usec;
     };

Note that DOS and Windows maintain the file times with 2-second
granularity.  Therefore, the `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 `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.

Return Value
------------

Zero on success, nonzero on failure.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     time_t now;
     struct timeval tvp[2];
     time(&now);
     tvp[1].tv_sec = now + 100;
     utimes("foo.dat", tvp);


File: libc.info,  Node: v2loadimage,  Next: valloc,  Prev: utimes,  Up: Alphabetical List

v2loadimage
===========

Syntax
------

     #include <debug/v2load.h>

     int v2loadimage (const char *program, const char *cmdline,
                      jmp_buf load_state);

Description
-----------

This function loads an executable image of a DJGPP v2.x program and
prepares it for debugging.  PROGRAM should point to the file name of
the executable program.  `v2loadimage' does *not* search the `PATH' and
does *not* try any executable extensions, so PROGRAM should point to a
fully-qualified path, complete with the drive, directory, and file-name
extension; otherwise the call will fail.

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 `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 LOAD_STATE so that it can be
used to `longjmp' to the debuggee's entry point.  This information is
typically used by `run_child' (*note run_child::).

Return Value
------------

Zero in case of success, non-zero otherwise.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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);


File: libc.info,  Node: valloc,  Next: varargs,  Prev: v2loadimage,  Up: Alphabetical List

valloc
======

Syntax
------

     #include <stdlib.h>

     void *valloc(size_t size);

Description
-----------

This function is just like `malloc' (*note malloc::) except the returned
pointer is a multiple of the CPU page size which is 4096 bytes.

Return Value
------------

A pointer to a newly allocated block of memory.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     char *page = valloc(getpagesize());


File: libc.info,  Node: varargs,  Next: vasnprintf,  Prev: valloc,  Up: Alphabetical List

varargs
=======

Syntax
------


     #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);

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 `...' in its argument list.  Then, you do the
following:

   *  Create a variable of type `va_list'.

   *  Initialize it by calling `va_start' with it and the name of the
     last required (i.e. non-variable) argument.

   *  Retrieve the arguments by calling `va_arg' with the `va_list'
     variable and the type of the argument.  As another alternative,
     you can pass the `va_list' to another function, which may then use
     `va_arg' to get at the arguments.  `vprintf' is an example of this.

   *  Call `va_end' to destroy the `va_list'.


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 `NULL') at the end.

Also, the variable arguments will be promoted according to standard C
promotion rules.  Arguments of type `char' and `short' will be promoted
to `int', and you should retrieve them as such.  Those of type `float'
will be promoted to `double'.

Return Value
------------

`va_arg' returns the argument it fetched, the other macros return
nothing.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------


     int find_the_sum(int count, ...)
     {
       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);
     }


File: libc.info,  Node: vasnprintf,  Next: vasprintf,  Prev: varargs,  Up: Alphabetical List

vasnprintf
==========

Syntax
------

     #include <stdio.h>
     #include <stdarg.h>

     char *vasnprintf(char *buffer, size_t *np, const char *format, va_list ap);

Description
-----------

Sends formatted output from the arguments in (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 BUFFER.
The buffer length must be passed by NP.  The function will write up to
*NP - 1 characters.  The *NPth character is used for the terminating
nul.  Upon error, `errno' is set and a `NULL' pointer is returned.

If BUFFER is a `NULL' pointer or *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 NP pointer.  The allocated memory must
be returned to the heap with `free' (*note free::).

Return Value
------------

If dynamic allocation occurs, a pointer to the newly allocated string
buffer is returned else BUFFER.  The number of characters that would
have been written (excluding the trailing nul) is returned by NP;
otherwise the function returns a `NULL' pointer.

The maximum accepted value of *NP is `INT_MAX'.  `INT_MAX' is defined
in `<limits.h>'.  A `NULL' pointer is returned and `errno' is set to
`EFBIG', if *NP is greater than this limit.

Portability
-----------

ANSI/ISO C   No (see note 1)
POSIX        No

Notes:

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


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.  */
     }


File: libc.info,  Node: vasprintf,  Next: vdprintf,  Prev: vasnprintf,  Up: Alphabetical List

vasprintf
=========

Syntax
------

     #include <stdio.h>
     #include <stdarg.h>

     int vasprintf(char **bufferp, const char *format, va_list ap);

Description
-----------

Sends formatted output from the arguments in (AP) including the
terminating null byte to the allocated buffer and returns a pointer to
it via the first parameter *BUFFERP.  This memory must be returned to
the heap with `free' (*note free::).  This function is analog of
`vsprintf()' (*note vsprintf::).

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 *BUFFERP is set to
`NULL'.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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.  */
     }


File: libc.info,  Node: vdprintf,  Next: vfork,  Prev: vasprintf,  Up: Alphabetical List

vdprintf
========

Syntax
------

     #include <stdio.h>

     int vdprintf(int file_desc, const char *format, va_list arguments);

Description
-----------

The function `vdprintf' is an exact analog of `vfprintf' (*note
vfprintf::), except that it output to a file descriptor FILE_DESC
instead of to a stdio stream.

Return Value
------------

The number of characters written is returned; otherwise EOF is returned
to flag encoding or buffer space errors.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: vfork,  Next: vfprintf,  Prev: vdprintf,  Up: Alphabetical List

vfork
=====

Syntax
------

     #include <unistd.h>

     pid_t vfork(void);

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.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: vfprintf,  Next: vfscanf,  Prev: vfork,  Up: Alphabetical List

vfprintf
========

Syntax
------

     #include <stdio.h>
     #include <stdarg.h>

     int vfprintf(FILE *file, const char *format, va_list arguments);

Description
-----------

Sends formatted output from the ARGUMENTS to the FILE.  *Note printf::.

Return Value
------------

The number of characters written.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     void my_errmsg(char *format, ...)
     {
       va_list arg;

       va_start(arg, format);
       fprintf(stderr, "my_errmsg: ");
       vfprintf(stderr, format, arg);
       va_end(arg);
     }


File: libc.info,  Node: vfscanf,  Next: vprintf,  Prev: vfprintf,  Up: Alphabetical List

vfscanf
=======

Syntax
------

     #include <stdio.h>

     int vfscanf(FILE *file, const char *format, va_list arguments);

Description
-----------

This function scans formatted text from FILE and stores it in the
variables pointed to by the ARGUMENTS.  *Note scanf::.

Return Value
------------

The number of items successfully scanned.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: vprintf,  Next: vscanf,  Prev: vfscanf,  Up: Alphabetical List

vprintf
=======

Syntax
------

     #include <stdio.h>
     #include <stdarg.h>

     int vprintf(const char *format, va_list arguments);

Description
-----------

Sends formatted output from the ARGUMENTS to `stdout'.  *Note printf::.
*Note vfprintf::.

Return Value
------------

The number of characters written.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: vscanf,  Next: vsnprintf,  Prev: vprintf,  Up: Alphabetical List

vscanf
======

Syntax
------

     #include <stdio.h>

     int vscanf(const char *format, va_list arguments);

Description
-----------

This function scans formatted text from `stdin' and stores it in the
variables pointed to by the ARGUMENTS. *Note scanf::.  *Note vfscanf::.

Return Value
------------

The number of items successfully scanned.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: vsnprintf,  Next: vsprintf,  Prev: vscanf,  Up: Alphabetical List

vsnprintf
=========

Syntax
------

     #include <stdio.h>
     #include <stdarg.h>

     int vsnprintf (char *buffer, size_t n, const char *format, va_list ap);

Description
-----------

This function works similarly to `vsprintf()' (*note vsprintf::), but
the size N of the BUFFER is also taken into account.  This function
will write N - 1 characters.  The Nth character is used for the
terminating nul.  If N is zero, BUFFER is not touched.

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 N is `INT_MAX'.  `INT_MAX' is defined in
`<limits.h>'.  -1 is returned and `errno' is set to `EFBIG', if N is
greater than this limit.

Portability
-----------

ANSI/ISO C   C89; C99; (see note 1)

Notes:

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



File: libc.info,  Node: vsprintf,  Next: vsscanf,  Prev: vsnprintf,  Up: Alphabetical List

vsprintf
========

Syntax
------

     #include <stdio.h>
     #include <stdarg.h>

     int vsprintf(char *buffer, const char *format, va_list arguments);

Description
-----------

Sends formatted output from the ARGUMENTS to the BUFFER.  *Note
printf::. *Note vfprintf::.

To avoid buffer overruns, it is safer to use `vsnprintf()' (*note
vsnprintf::).

Return Value
------------

The number of characters written.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: vsscanf,  Next: wait,  Prev: vsprintf,  Up: Alphabetical List

vsscanf
=======

Syntax
------

     #include <stdio.h>

     int vsscanf(const char *string, const char *format, va_list arguments);

Description
-----------

This function scans formatted text from the STRING and stores it in the
variables pointed to by the ARGUMENTS. *Note scanf::.  *Note vfscanf::.

Return Value
------------

The number of items successfully scanned.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: wait,  Next: waitpid,  Prev: vsscanf,  Up: Alphabetical List

wait
====

Syntax
------

     #include <sys/wait.h>

     pid_t pid = wait(int *status);

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 `errno' is set.

Return Value
------------

If successful, this function returns the exit status of the child.  If
there is an error, these functions return -1 and set `errno' to
indicate the error type.

Bugs
----

Currently, this function always fails.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: waitpid,  Next: wcstombs,  Prev: wait,  Up: Alphabetical List

waitpid
=======

Syntax
------

     #include <sys/wait.h>

     pid_t pid = waitpid((pid_t pid, int *status, int options);

Description
-----------

Currently, this function always fails. A -1 is returned and `errno' is
set to indicate there are no children.

Return Value
------------

If successful, this function returns the exit status of the child.  If
there is an error, these functions return -1 and set `errno' to
indicate the error type.

Bugs
----

Currently, this function always fails.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008


File: libc.info,  Node: wcstombs,  Next: wctomb,  Prev: waitpid,  Up: Alphabetical List

wcstombs
========

Syntax
------

     #include <stdlib.h>

     size_t wcstombs(char *s, const wchar_t *wcs, size_t n);

Description
-----------

Converts a wide character string to a multibyte string.  At most N
characters are stored.

Return Value
------------

The number of characters stored.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     int len = wcstombs(buf, wstring, sizeof(buf));


File: libc.info,  Node: wctomb,  Next: wherex,  Prev: wcstombs,  Up: Alphabetical List

wctomb
======

Syntax
------

     #include <stdlib.h>

     int wctomb(char *s, wchar_t wchar);

Description
-----------

Convert a wide character to a multibyte character.  The string S must
be at least `MB_LEN_MAX' bytes long.

Return Value
------------

The number of characters stored.

Portability
-----------

ANSI/ISO C   C89; C99
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

     char s[MB_LEN_MAX];
     int mlen = wctomb(s, wc);


File: libc.info,  Node: wherex,  Next: wherey,  Prev: wctomb,  Up: Alphabetical List

wherex
======

Syntax
------

     #include <conio.h>

     int wherex(void);

Return Value
------------

The column the cursor is on.  The leftmost column is 1.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: wherey,  Next: wild,  Prev: wherex,  Up: Alphabetical List

wherey
======

Syntax
------

     #include <conio.h>

     int     wherey(void);

Return Value
------------

The row the cursor is on.  The topmost row is 1.

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: wild,  Next: window,  Prev: wherey,  Up: Alphabetical List

wild
====

Syntax
------

     #include <debug/wild.h>

     int wild (char *pattern, char *string);

Description
-----------

This function matches a string pointed to by STRING against a pattern
pointed to by PATTERN.  PATTERN may include wildcard characters `?' and
`*', 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.

Return Value
------------

The function returns non-zero if the string matches the pattern, zero
otherwise.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: window,  Next: write,  Prev: wild,  Up: Alphabetical List

window
======

Syntax
------

     #include <conio.h>

     void    window(int _left, int _top, int _right, int _bottom);

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).

Portability
-----------

ANSI/ISO C   No
POSIX        No

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 `gppconio_init' function manually
(this is the function called by a static constructor).


File: libc.info,  Node: write,  Next: _write,  Prev: window,  Up: Alphabetical List

write
=====

Syntax
------

     #include <unistd.h>

     int write(int file, const void *buffer, size_t count);

Description
-----------

This function writes COUNT bytes from BUFFER to FILE.  It returns the
number of bytes actually written.  It will return zero or a number less
than COUNT if the disk is full, and may return less than COUNT even
under valid conditions.

Note that if FILE is a text file, `write' may write more bytes than it
reports.

If COUNT is zero, the function does nothing and returns zero.  Use
`_write' if you want to actually ask DOS to write zero bytes.

The precise behavior of `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 `errno' being set to
`ENOSPC' in such cases, you need to invoke `write' as shown in the
example below.  In a nutshell, the trick is to call `write' one more
time after it returns a value smaller than the COUNT parameter; then it
will _always_ set `errno' if the disk is full.

Return Value
------------

The number of bytes written, zero at EOF, or -1 on error.

Portability
-----------

ANSI/ISO C   No
POSIX        1003.2-1992; 1003.1-2001; 1003.1-2008

Example
-------

This example shows how to call `write' in a way which ensures that
`errno' will be set to `ENOSPC' if the target filesystem is or becomes
full:

       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;
       }


File: libc.info,  Node: _write,  Next: write_child,  Prev: write,  Up: Alphabetical List

_write
======

Syntax
------

     #include <io.h>

     ssize_t _write(int fildes, const void *buf, size_t nbyte);

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 *Note File System Extensions::.  If you don't want this,
you should use `_dos_write' instead, see *Note _dos_write::.

Return Value
------------

The number of bytes written, or -1 (and `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,
`_write' does *not* return -1, it returns the number of bytes it
succeeded to write.  If you need to detect the disk full condition
reliably, call `_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
_then_ `_write' will return -1 and set `errno' to `ENOSPC'.  The
example below shows one way of doing this.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

This example shows how to call `_write' in a way which ensures that
`errno' will be set to `ENOSPC' if the target filesystem is or becomes
full:

       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;
       }


File: libc.info,  Node: write_child,  Next: write_sel_addr,  Prev: _write,  Up: Alphabetical List

write_child
===========

Syntax
------

     #include <debug/dbgcom.h>

     int write_child (unsigned child_addr, void *buf, unsigned len);

Description
-----------

This function transfers LEN bytes from the buffer pointed to by BUF in
the debugger's data segment to the memory of the debugged process
starting at the address 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
`read_child' (*note read_child::) is usually called before
`write_child' to save the original code overwritten by the breakpoint
instruction.

Return Value
------------

The function return zero if it has successfully transferred the data,
non-zero otherwise (e.g., if the address in CHILD_ADDR is outside the
limits of the debuggee's code segment.

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: write_sel_addr,  Next: writev,  Prev: write_child,  Up: Alphabetical List

write_sel_addr
==============

Syntax
------

     #include <debug/dbgcom.h>

     int write_sel_addr (unsigned sel, unsigned offset,
                         void *buf, unsigned len);

Description
-----------

This function transfers LEN bytes from the buffer pointed to by BUF in
the data segment whose selector is SEL, at offset OFFSET.  The
companion function `read_sel_addr' (*note read_sel_addr::) is usually
called before `write_sel_addr' to save the original contents, if needed.

Return Value
------------

The function return zero if it has successfully transferred the data,
non-zero otherwise (e.g., if the address in OFFSET is outside the
limits of the SELs segment).

Portability
-----------

ANSI/ISO C   No
POSIX        No


File: libc.info,  Node: writev,  Next: xfree,  Prev: write_sel_addr,  Up: Alphabetical List

writev
======

Syntax
------

     #include <sys/uio.h>

     ssize_t writev(int fd, const struct iovec *iov, int iovcnt);

Description
-----------

`writev' performs a scatter-gather write to the specified file
descriptor FD.  A group of buffers described by the array IOV, with
IOVCNT entries, is written to FD in a similar way to `write' (*note
write: (libc)write.).

`struct iovec' is defined as follows:

     struct iovec {
       void   *iov_base; /* Base address of a memory region for I/O */
       size_t  iov_len;  /* Size of memory region                   */
     };

Return Value
------------

On successful completion the function returns the number of bytes
written.  Otherwise, a value of -1 is returned and `errno' is set
appropriately.

`EINVAL'
     One of the following conditions is true:

        * The total length to write would overflow a `ssize_t'.

        * IOVCNT was negative, zero or larger than `IOV_MAX'.


Portability
-----------

ANSI/ISO C   No
POSIX        1003.1-2001; 1003.1-2008; not 1003.2-1992


File: libc.info,  Node: xfree,  Next: xmalloc,  Prev: writev,  Up: Alphabetical List

xfree
=====

Syntax
------

     #include <stdlib.h>

     void xfree(void *ptr);

Description
-----------

Frees memory allocated by `xmalloc' (*note xmalloc::).  This function
guarantees that a NULL pointer is handled gracefully.

Note that, currently, the header `stdlib.h' does *not* declare a
prototype for `xfree', because many programs declare its prototype in
different and conflicting ways.  If you use `xfree' in your own code,
you might need to provide your own prototype explicitly.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     void *f = xmalloc(100);
     xfree(f);


File: libc.info,  Node: xmalloc,  Next: xrealloc,  Prev: xfree,  Up: Alphabetical List

xmalloc
=======

Syntax
------

     #include <stdlib.h>

     void *xmalloc(size_t size);

Description
-----------

This function is just like `malloc' (*note malloc::), except that if
there is no more memory, it prints an error message and exits.

Note that, currently, the header `stdlib.h' does *not* declare a
prototype for `xmalloc', because many programs declare its prototype in
different and conflicting ways.  If you use `xmalloc' in your own code,
you might need to provide your own prototype explicitly.

Return Value
------------

A pointer to the newly allocated memory.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     char *f = xmalloc(100);


File: libc.info,  Node: xrealloc,  Prev: xmalloc,  Up: Alphabetical List

xrealloc
========

Syntax
------

     #include <stdlib.h>

     void *xrealloc(void *ptr, size_t size);

Description
-----------

This function is just like `realloc' (*note realloc::), except that if
there is no more memory, it prints an error message and exits.  It can
also properly handle PTR being `NULL'.

Note that, currently, the header `stdlib.h' does *not* declare a
prototype for `xrealloc', because many programs declare its prototype
in different and conflicting ways.  If you use `xrealloc' in your own
code, you might need to provide your own prototype explicitly.

Return Value
------------

A pointer to a possibly new block.

Portability
-----------

ANSI/ISO C   No
POSIX        No

Example
-------

     char *buf;
     buf = (char *)xrealloc(buf, new_size);


File: libc.info,  Node: Unimplemented,  Next: Function Index,  Prev: Alphabetical List,  Up: Top

2 Unimplemented Functions
*************************

The DJGPP standard C library is ANSI- and POSIX-compliant, and provides
many additional functions for compatibility with Unix/Linux systems.
However, some of the functions needed for this compatibility are very
hard or impossible to implement using DOS facilities.

Therefore, a small number of library functions are really just stubs:
they are provided because POSIX requires them to be present in a
compliant library, or because they are widely available on Unix systems,
but they either always fail, or handle only the trivial cases and fail
for all the others.  An example of the former behavior is the function
`fork': it always returns a failure indication; an example of the
latter behavior is the function `mknode': it handles the cases of
regular files and existing character devices, but fails for all other
file types.

This chapter lists all such functions.  This list is here for the
benefit of programmers who write portable programs or port Unix packages
to DJGPP.

Each function below is labeled as either "always fails" or "trivial",
depending on which of the two classes described above it belongs to.
An additional class, labeled "no-op", includes functions which pretend
to succeed, but have no real effect, since the underlying functionality
is either always available or always ignored.

* Menu:

* addmntent::                Always fails.
* cfgetispeed::              No-op.
* cfgetospeed::              No-op.
* cfsetispeed::              No-op.
* cfsetospeed::              No-op.
* chown::                    Trivial.
* fchown::                   Trivial.
* fork::                     Always fails.
* getgrgid::                 Trivial.
* getgrnam::                 Trivial.
* getgroups::                Trivial.
* getpwnam::                 Trivial.
* getpwuid::                 Trivial.
* lchown::                   Trivial.
* mkfifo::                   Always fails.
* mknod::                    Trivial.
* nice::                     No-op.
* setgid::                   Trivial.
* setpgid::                  Trivial.
* setsid::                   Trivial.
* setuid::                   Trivial.
* tcdrain::                  No-op.
* tcsendbreak::              No-op.
* tcsetpgrp::                Trivial.
* umask::                    Trivial.
* vfork::                    Always fails.
* wait::                     Always fails.
* waitpid::                  Always fails.


File: libc.info,  Node: Function Index,  Next: Variable Index,  Prev: Unimplemented,  Up: Top

Function Index
**************

[index]
* Menu:

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


File: libc.info,  Node: Variable Index,  Next: Data Type Index,  Prev: Function Index,  Up: Top

Variable Index
**************

[index]
* Menu:

* 387 environment variable, and math coprocessor detection: _8087.
                                                               (line  6)
* 387 environment variable, and numeric coprocessor detection: _8087.
                                                               (line  6)
* _8087:                                 _8087.                (line  6)
* __djgpp_memory_handle_list:            __djgpp_memory_handle_list.
                                                               (line  6)
* __djgpp_memory_handle_size:            __djgpp_memory_handle_size.
                                                               (line  6)
* __djgpp_stack_overflow_eip:            Stack overflow handler.
                                                               (line  6)
* __dpmi_error:                          DPMI Overview.        (line  6)
* _crt0_startup_flags:                   _crt0_startup_flags.  (line  6)
* _djstat_fail_bits:                     _djstat_fail_bits.    (line  6)
* _djstat_flags:                         _djstat_flags.        (line  6)
* _doserrno:                             _doserrno.            (line  6)
* _fmode:                                _fmode.               (line  6)
* _go32_info_block:                      _go32_info_block.     (line  6)
* _go32_interrupt_stack_size:            _go32_interrupt_stack_size.
                                                               (line  6)
* _go32_rmcb_stack_size:                 _go32_rmcb_stack_size.
                                                               (line  6)
* _stklen:                               _stklen.              (line  6)
* CMDLINE environment variable, and spawn*: spawn*.            (line  6)
* CMDLINE environment variable, and system: system.            (line  6)
* COMSPEC environment variable, and password file entries: getpwent.
                                                               (line  6)
* COMSPEC environment variable, and spawn*: spawn*.            (line  6)
* COMSPEC environment variable, and system: system.            (line  6)
* DJGPP environment variable:            __crt0_load_environment_file.
                                                               (line  6)
* DJSYSFLAGS environment variable, and the behaviour of system: system.
                                                               (line  6)
* errno:                                 errno.                (line  6)
* FNCASE environment variable:           _preserve_fncase.     (line  6)
* FNCASE environment variable, and file-name globbing: glob.   (line  6)
* FNCASE environment variable, how to disable at start-up: _crt0_startup_flags.
                                                               (line  6)
* GROUP environment variable, and group entries: getgrent.     (line  6)
* HOME environment variable, and password file entries: getpwent.
                                                               (line  6)
* HOSTNAME environment variable:         gethostname.          (line  6)
* LD_LIBRARY_PATH:                       dlopen.               (line 21)
* LFN environment variable:              _use_lfn.             (line  6)
* LFN environment variable and _rename:  _rename.              (line  6)
* LFN environment variable, and file-name case: _preserve_fncase.
                                                               (line  6)
* LFN environment variable, and file-name globbing: glob.      (line  6)
* LFN environment variable, how to disable at start-up: _crt0_startup_flags.
                                                               (line  6)
* llrint:                                llrint.               (line  6)
* llrintf:                               llrintf.              (line  6)
* llrintl:                               llrintl.              (line  6)
* LOGNAME environment variable, and the user's login ID: getlogin.
                                                               (line  6)
* lrint:                                 lrint.                (line  6)
* lrintf:                                lrintf.               (line  6)
* lrintl:                                lrintl.               (line  6)
* math_errhandling:                      math_errhandling.     (line  6)
* PATH environment variable, and finding files with searchpath: searchpath.
                                                               (line  6)
* PATH environment variable, and spawn*: spawn*.               (line  6)
* ScreenAttrib:                          Screen Variables.     (line  6)
* ScreenPrimary:                         Screen Variables.     (line  6)
* ScreenSecondary:                       Screen Variables.     (line  6)
* SHELL environment variable, and password file entries: getpwent.
                                                               (line  6)
* SHELL environment variable, and system: system.              (line  6)
* sys_errlist:                           sys_errlist.          (line  6)
* sys_nerr:                              sys_nerr.             (line  6)
* TEMP environment variable, and tempnam: tempnam.             (line  6)
* TEMP environment variable, and tmpnam: tmpnam.               (line  6)
* TMP environment variable, and tempnam: tempnam.              (line  6)
* TMP environment variable, and tmpnam:  tmpnam.               (line  6)
* TMPDIR environment variable, and tempnam: tempnam.           (line  6)
* TMPDIR environment variable, and tmpnam: tmpnam.             (line  6)
* TZ environment variable, and time since 1970: mktime.        (line  6)
* TZ environment variable, and tzname:   tzset.                (line  6)
* tzname:                                tzset.                (line  6)
* USER environment variable, and the user's login ID: getlogin.
                                                               (line  6)
* USERNAME environment variable, and the user's login ID: getlogin.
                                                               (line  6)


File: libc.info,  Node: Data Type Index,  Next: Concept Index,  Prev: Variable Index,  Up: Top

Data Type Index
***************

[index]
* Menu:

* __dpmi_callback_info type:             DPMI Overview.         (line 6)
* __dpmi_free_mem_info type:             DPMI Overview.         (line 6)
* __dpmi_meminfo type:                   DPMI Overview.         (line 6)
* __dpmi_memory_info type:               DPMI Overview.         (line 6)
* __dpmi_paddr type:                     DPMI Overview.         (line 6)
* __dpmi_raddr type:                     DPMI Overview.         (line 6)
* __dpmi_regs type:                      DPMI Overview.         (line 6)
* __dpmi_shminfo type:                   DPMI Overview.         (line 6)
* __dpmi_version_ret type:               DPMI Overview.         (line 6)
* _go32_dpmi_meminfo type:               _go32_dpmi_get_free_memory_information.
                                                                (line 6)
* _v1_stubinfo type:                     _check_v2_prog.        (line 6)
* _v2_prog_type type:                    _check_v2_prog.        (line 6)
* ACTION type:                           hsearch.               (line 6)
* BYTEREGS structure:                    int86.                 (line 6)
* cmdline_t type:                        redir_debug_init.      (line 6)
* date structure:                        getdate.               (line 6)
* dbg_redirect structure:                redir_debug_init.      (line 6)
* dfree structure:                       getdfree.              (line 6)
* dirent structure:                      readdir.               (line 6)
* diskfree_t structure:                  _dos_getdiskfree.      (line 6)
* diskinfo_t structure:                  _bios_disk.            (line 6)
* div_t type:                            div.                   (line 6)
* dosdate_t structure:                   _dos_getdate.          (line 6)
* DOSERROR structure:                    dosexterr.             (line 6)
* DOSERROR_STR structure:                dostrerr.              (line 6)
* dostime_t structure:                   _dos_gettime.          (line 6)
* DWORDREGS structure:                   int86.                 (line 6)
* DWORDREGS_W structure:                 int86.                 (line 6)
* ENTRY type:                            hsearch.               (line 6)
* exception structure:                   matherr.               (line 6)
* fd_properties structure:               __set_fd_properties.   (line 6)
* ffblk structure:                       findfirst.             (line 6)
* find_t structure:                      _dos_findfirst.        (line 6)
* ftime structure:                       getftime.              (line 6)
* glob_t type:                           glob.                  (line 6)
* Go32_Info_Block type:                  _go32_info_block.      (line 6)
* group structure:                       getgrent.              (line 6)
* imaxdiv_t type:                        imaxdiv.               (line 6)
* iovec structure:                       readv.                 (line 6)
* itimerval structure:                   setitimer.             (line 6)
* lconv structure:                       localeconv.            (line 6)
* ldiv_t type:                           ldiv.                  (line 6)
* lldiv_t type:                          lldiv.                 (line 6)
* mntent structure:                      getmntent.             (line 6)
* NPX type:                              save_npx.              (line 6)
* NPXREG type:                           save_npx.              (line 6)
* passwd structure:                      getpwent.              (line 6)
* qelem structure:                       insque.                (line 6)
* regex_t type:                          regcomp.               (line 6)
* REGS union:                            int86.                 (line 6)
* rlimit structure:                      getrlimit.             (line 6)
* rusage structure:                      getrusage.             (line 6)
* sigaction structure:                   sigaction.             (line 6)
* SREGS structure:                       int86x.                (line 6)
* stat structure:                        stat.                  (line 6)
* statfs structure:                      statfs.                (line 6)
* statvfs structure:                     statvfs.               (line 6)
* termios structure:                     Termios functions.     (line 6)
* text_info structure:                   gettextinfo.           (line 6)
* time structure:                        gettime.               (line 6)
* timeb structure:                       ftime.                 (line 6)
* timeval structure:                     gettimeofday.          (line 6)
* timezone structure:                    gettimeofday.          (line 6)
* tm structure:                          gmtime.                (line 6)
* tms structure:                         times.                 (line 6)
* TSS structure:                         run_child.             (line 6)
* TSS type:                              run_child.             (line 6)
* utimbuf structure:                     utime.                 (line 6)
* utsname structure:                     uname.                 (line 6)
* winsize structure:                     ioctl (UNIX).          (line 6)
* WORDREGS structure:                    int86.                 (line 6)


File: libc.info,  Node: Concept Index,  Prev: Data Type Index,  Up: Top

Concept Index
*************

[index]
* Menu:

* cooked mode:                           _get_dev_info.        (line  6)
* fd_properties:                         __set_fd_properties.  (line  6)
* fd_props:                              __set_fd_properties.  (line  6)
* file descriptor properties:            __set_fd_properties.  (line  6)
* File System Extensions:                File System Extensions.
                                                               (line  6)
* FSEXT:                                 File System Extensions.
                                                               (line  6)
* locale code format:                    setlocale.            (line 49)
* radix-64:                              l64a.                 (line 31)
* raw mode:                              _get_dev_info.        (line  6)
* termios:                               Termios functions.    (line  6)



Tag Table:
Node: Top151
Node: Introduction639
Node: Functional Categories1958
Node: bios functions2782
Node: conio functions3201
Node: cpu functions4072
Node: ctype functions4616
Node: debugging functions4999
Node: dos functions5567
Node: dpmi functions6342
Node: environment functions10294
Node: file system functions10525
Node: go32 functions11807
Node: io functions12215
Node: locale functions13127
Node: math functions13399
Node: memory functions14365
Node: misc functions15336
Node: mono functions15914
Node: posix functions16120
Node: process functions16350
Node: profiling functions16787
Node: random number functions17001
Node: search functions17272
Node: shell functions17482
Node: signal functions17668
Node: sound functions18147
Node: startup functions18334
Node: stdio functions18623
Node: string functions19723
Node: sys functions20557
Node: termios functions20726
Node: time functions21168
Node: unistd functions21660
Node: unix functions21844
Node: Alphabetical List22544
Node: _808737207
Node: a64l37785
Node: abort39125
Node: abs39936
Node: access40329
Node: acos41316
Node: acosh41926
Node: addmntent42393
Node: alarm42872
Node: alloca44084
Node: asctime44653
Node: asctime_r45677
Node: asin46569
Node: asinh47106
Node: asnprintf47693
Node: asprintf49976
Node: assert51320
Node: atan52619
Node: atan253279
Node: atanh54444
Node: atexit55066
Node: atof55883
Node: atoi56546
Node: atol57195
Node: _atold57848
Node: atoll58498
Node: basename59200
Node: bcmp60383
Node: bcopy61042
Node: bdos61571
Node: bdosptr62400
Node: _bios_disk63587
Node: _bios_equiplist68447
Node: _bios_keybrd69715
Node: _bios_memsize73361
Node: _bios_printer73880
Node: _bios_serialcom75246
Node: _bios_timeofday78209
Node: bioscom79243
Node: biosdisk81942
Node: biosequip84060
Node: bioskey85489
Node: biosmemory88711
Node: biosprint89340
Node: biostime90168
Node: blinkvideo90705
Node: brk91709
Node: bsearch92403
Node: bzero93737
Node: calloc94150
Node: cbrt94969
Node: ceil95541
Node: cfgetispeed95989
Node: cfgetospeed96717
Node: cfmakeraw97449
Node: cfree97968
Node: cfsetispeed98431
Node: cfsetospeed99153
Node: cfsetspeed99881
Node: cgets100443
Node: chdir101692
Node: _check_v2_prog102416
Node: chmod106122
Node: _chmod107451
Node: chown108776
Node: chsize109467
Node: cleanup_client109841
Node: _clear87110461
Node: __clear_fd_flags110856
Node: __clear_fd_properties111592
Node: clearerr112390
Node: clock112859
Node: close113475
Node: _close113977
Node: closedir114510
Node: clreol114951
Node: clrscr115867
Node: confstr116751
Node: _conio_gettext118656
Node: _conio_kbhit119088
Node: _control87120296
Node: cos124658
Node: cosh125931
Node: cprintf126646
Node: cputs127795
Node: creat128772
Node: _creat129593
Node: _creatnew130712
Node: crlf2nl133650
Node: __crt0_glob_function134091
Node: __crt0_load_environment_file134925
Node: __crt0_setup_arguments135706
Node: _crt0_startup_flags136719
Node: cscanf142793
Node: ctermid143929
Node: ctime144462
Node: ctime_r145392
Node: delay146228
Node: delline147692
Node: _detect_80387148627
Node: difftime149217
Node: dirname149812
Node: disable150903
Node: div151498
Node: __djgpp_exception_toggle152307
Node: __djgpp_map_physical_memory153270
Node: __djgpp_memory_handle154962
Node: __djgpp_memory_handle_list155656
Node: __djgpp_memory_handle_size156648
Node: __djgpp_nearptr_disable157597
Node: __djgpp_nearptr_enable158057
Node: __djgpp_set_ctrl_c159719
Node: __djgpp_set_page_attributes161971
Node: __djgpp_set_sigint_key163335
Node: __djgpp_set_sigquit_key165592
Node: __djgpp_share_flags167820
Node: __djgpp_spawn169462
Node: __djgpp_traceback_exit170651
Node: _djstat_describe_lossage171490
Node: _djstat_fail_bits173748
Node: _djstat_flags177372
Node: dlclose180573
Node: dlerror181192
Node: dlerrstatmod181721
Node: dlerrstatsym182388
Node: dlopen182906
Node: dlregsym184320
Node: dlsym185256
Node: _dlsymresolver186020
Node: dlunregsym187081
Node: _doprnt187618
Node: _dos_close188318
Node: _dos_commit189040
Node: _dos_creat189683
Node: _dos_creatnew191200
Node: _dos_findfirst192733
Node: _dos_findnext194978
Node: _dos_getdate195822
Node: _dos_getdiskfree196634
Node: _dos_getdrive197948
Node: _dos_getfileattr198559
Node: _dos_getftime200302
Node: _dos_gettime202582
Node: _dos_lk64203343
Node: _dos_lock203992
Node: _dos_open204420
Node: _dos_read206351
Node: _dos_setdate207827
Node: _dos_setdrive208868
Node: _dos_setfileattr209630
Node: _dos_setftime210899
Node: _dos_settime212701
Node: _dos_unlk64213662
Node: _dos_unlock214326
Node: _dos_write214766
Node: _doscan216285
Node: _doserrno217134
Node: __dosexec_find_on_path217811
Node: dosexterr219823
Node: dosmemget233992
Node: dosmemgetb234921
Node: dosmemgetl235895
Node: dosmemgetw236888
Node: dosmemput237877
Node: dosmemputb238773
Node: dosmemputl239743
Node: dosmemputw240723
Node: dostrerr241703
Node: DPMI Overview244183
Node: DPMI Specification249234
Node: __dpmi_allocate_dos_memory249574
Node: __dpmi_allocate_ldt_descriptors250645
Node: __dpmi_allocate_linear_memory251557
Node: __dpmi_allocate_memory252515
Node: __dpmi_allocate_real_mode_callback253241
Node: __dpmi_allocate_shared_memory254344
Node: __dpmi_allocate_specific_ldt_descriptor255687
Node: __dpmi_clear_debug_watchpoint256438
Node: __dpmi_create_alias_descriptor257150
Node: __dpmi_discard_page_contents257897
Node: __dpmi_free_dos_memory258683
Node: __dpmi_free_ldt_descriptor259454
Node: __dpmi_free_memory260230
Node: __dpmi_free_physical_address_mapping260903
Node: __dpmi_free_real_mode_callback261772
Node: __dpmi_free_serialization_on_shared_memory262521
Node: __dpmi_free_shared_memory263701
Node: __dpmi_get_and_disable_virtual_interrupt_state264565
Node: __dpmi_get_and_enable_virtual_interrupt_state265370
Node: __dpmi_get_and_set_virtual_interrupt_state266188
Node: __dpmi_get_capabilities267195
Node: __dpmi_get_coprocessor_status268460
Node: __dpmi_get_descriptor269634
Node: __dpmi_get_descriptor_access_rights275324
Node: __dpmi_get_extended_exception_handler_vector_pm276201
Node: __dpmi_get_extended_exception_handler_vector_rm277123
Node: __dpmi_get_free_memory_information278038
Node: __dpmi_get_memory_block_size_and_base278879
Node: __dpmi_get_memory_information279698
Node: __dpmi_get_multiple_descriptors282056
Node: __dpmi_get_page_attributes283182
Node: __dpmi_get_page_size284689
Node: __dpmi_get_processor_exception_handler_vector285378
Node: __dpmi_get_protected_mode_interrupt_vector286360
Node: __dpmi_get_raw_mode_switch_addr287305
Node: __dpmi_get_real_mode_interrupt_vector288096
Node: __dpmi_get_segment_base_address289098
Node: __dpmi_get_segment_limit290014
Node: __dpmi_get_selector_increment_value290681
Node: __dpmi_get_state_of_debug_watchpoint291440
Node: __dpmi_get_state_save_restore_addr292314
Node: __dpmi_get_vendor_specific_api_entry_point293132
Node: __dpmi_get_version293983
Node: __dpmi_get_virtual_interrupt_state294952
Node: __dpmi_install_resident_service_provider_callback295676
Node: __dpmi_int297333
Node: __dpmi_lock_linear_region298440
Node: __dpmi_map_conventional_memory_in_memory_block299219
Node: __dpmi_map_device_in_memory_block300194
Node: __dpmi_mark_page_as_demand_paging_candidate301195
Node: __dpmi_mark_real_mode_region_as_pageable302042
Node: __dpmi_physical_address_mapping302891
Node: __dpmi_relock_real_mode_region303757
Node: __dpmi_reset_debug_watchpoint304569
Node: __dpmi_resize_dos_memory305289
Node: __dpmi_resize_linear_memory306175
Node: __dpmi_resize_memory307097
Node: __dpmi_segment_to_descriptor307953
Node: __dpmi_serialize_on_shared_memory308887
Node: __dpmi_set_coprocessor_emulation310325
Node: __dpmi_set_debug_watchpoint311570
Node: __dpmi_set_descriptor312388
Node: __dpmi_set_descriptor_access_rights313308
Node: __dpmi_set_extended_exception_handler_vector_pm314835
Node: __dpmi_set_extended_exception_handler_vector_rm315758
Node: __dpmi_set_multiple_descriptors316672
Node: __dpmi_set_page_attributes317685
Node: __dpmi_set_processor_exception_handler_vector319026
Node: __dpmi_set_protected_mode_interrupt_vector319929
Node: __dpmi_set_real_mode_interrupt_vector321063
Node: __dpmi_set_segment_base_address322016
Node: __dpmi_set_segment_limit322779
Node: __dpmi_simulate_real_mode_interrupt323786
Node: __dpmi_simulate_real_mode_procedure_iret324767
Node: __dpmi_simulate_real_mode_procedure_retf325677
Node: __dpmi_simulate_real_mode_procedure_retf_stack326627
Node: __dpmi_terminate_and_stay_resident328092
Node: __dpmi_unlock_linear_region329542
Node: __dpmi_yield330270
Node: dprintf331209
Node: DTTOIF331837
Node: dup332717
Node: dup2333220
Node: __dup_fd_properties333859
Node: _dxe_load334538
Node: DXE_macros335370
Node: ecvt336549
Node: ecvtbuf337166
Node: edi_init338756
Node: enable339653
Node: endgrent340251
Node: endmntent340671
Node: endpwent341095
Node: errno341472
Node: exec*348861
Node: __exit350061
Node: _exit350769
Node: _Exit351488
Node: exit352377
Node: exp352991
Node: exp10353892
Node: exp2354665
Node: expm1355436
Node: fabs356385
Node: _far*356926
Node: fchdir359675
Node: fchmod360225
Node: fchown362029
Node: fclose362700
Node: fcntl363188
Node: fcvt371869
Node: fcvtbuf372481
Node: fdopen374470
Node: feof375107
Node: ferror375614
Node: fflush376142
Node: ffs377358
Node: fgetc377881
Node: fgetgrent378415
Node: fgetpos378772
Node: fgets379275
Node: File System Extensions380144
Node: __file_exists388561
Node: __file_tree_walk389330
Node: filelength392094
Node: fileno392997
Node: findfirst393429
Node: findnext396648
Node: _fixpath397077
Node: flock398640
Node: floor401457
Node: _flush_disk_cache401950
Node: fmod402835
Node: _fmode403456
Node: fnmatch403960
Node: fnmerge406989
Node: fnsplit407879
Node: fopen409283
Node: fork411738
Node: fpathconf412180
Node: fpclassify412835
Node: __fpclassifyd413703
Node: __fpclassifyf414373
Node: __fpclassifyld415047
Node: _fpreset415741
Node: fprintf416037
Node: fpurge416488
Node: fputc417049
Node: fputs417530
Node: fread418066
Node: free418641
Node: freopen419128
Node: frexp419794
Node: fscanf420529
Node: fseek421041
Node: fseeko422689
Node: fsetpos424521
Node: __FSEXT_add_open_handler425053
Node: __FSEXT_alloc_fd425781
Node: __FSEXT_call_open_handlers427192
Node: __FSEXT_get_data427798
Node: __FSEXT_get_function428546
Node: __FSEXT_set_data429312
Node: __FSEXT_set_function432423
Node: fstat434291
Node: fstatvfs438563
Node: fsync440163
Node: ftell440773
Node: ftello441271
Node: ftime441947
Node: ftruncate442772
Node: ftw443584
Node: _fwalk448026
Node: fwrite448548
Node: gcvt449133
Node: _get_dev_info450193
Node: _get_dos_version453117
Node: __get_extended_key_string455228
Node: _get_fat_size458874
Node: __get_fd_flags460307
Node: __get_fd_name461194
Node: _get_fs_type461785
Node: _get_volume_info463592
Node: getc465833
Node: getcbrk466332
Node: getch466717
Node: getchar468133
Node: getche468525
Node: getcwd469936
Node: getdate470972
Node: getdfree471528
Node: getdisk472319
Node: getdtablesize472752
Node: getegid473135
Node: getenv473492
Node: geteuid474027
Node: getftime474375
Node: getgid475156
Node: getgrent475504
Node: getgrgid476694
Node: getgrnam477197
Node: getgroups477705
Node: gethostname478141
Node: getitimer479075
Node: getkey480237
Node: getlogin480866
Node: getlongpass481698
Node: getmntent482612
Node: getopt486830
Node: getpagesize489224
Node: getpass489622
Node: getpgrp490496
Node: getpid490899
Node: getppid491314
Node: getpwent491771
Node: getpwnam493492
Node: getpwuid494006
Node: getrlimit494513
Node: getrusage496043
Node: gets497779
Node: gettext498455
Node: gettextinfo500167
Node: gettime501657
Node: gettimeofday502276
Node: getuid503430
Node: getw503773
Node: getwd504476
Node: getxkey504937
Node: glob505557
Node: globfree512091
Node: gmtime512501
Node: gmtime_r514129
Node: _go32_conventional_mem_selector515030
Node: _go32_dpmi_allocate_dos_memory516184
Node: _go32_dpmi_allocate_iret_wrapper517469
Node: _go32_dpmi_allocate_real_mode_callback_iret518994
Node: _go32_dpmi_allocate_real_mode_callback_retf520832
Node: _go32_dpmi_chain_protected_mode_interrupt_vector522125
Node: _go32_dpmi_free_dos_memory523278
Node: _go32_dpmi_free_iret_wrapper524099
Node: _go32_dpmi_free_real_mode_callback524805
Node: _go32_dpmi_get_free_memory_information525593
Node: _go32_dpmi_get_protected_mode_interrupt_vector526955
Node: _go32_dpmi_get_real_mode_interrupt_vector527923
Node: _go32_dpmi_lock_code528733
Node: _go32_dpmi_lock_data529551
Node: _go32_dpmi_remaining_physical_memory530277
Node: _go32_dpmi_remaining_virtual_memory530826
Node: _go32_dpmi_resize_dos_memory531379
Node: _go32_dpmi_set_protected_mode_interrupt_vector532389
Node: _go32_dpmi_set_real_mode_interrupt_vector534325
Node: _go32_dpmi_simulate_fcall535147
Node: _go32_dpmi_simulate_fcall_iret536329
Node: _go32_dpmi_simulate_int537522
Node: _go32_info_block538716
Node: _go32_interrupt_stack_size542238
Node: _go32_my_cs542663
Node: _go32_my_ds543076
Node: _go32_my_ss543459
Node: _go32_rmcb_stack_size543852
Node: _go32_want_ctrl_break544271
Node: _go32_was_ctrl_break_hit545244
Node: gotoxy546081
Node: gppconio_init547063
Node: __has_fd_properties547607
Node: _hash2v548110
Node: hasmntopt549104
Node: hcreate549669
Node: hdestroy550599
Node: highvideo551505
Node: hsearch552436
Node: htonl554559
Node: htons555120
Node: hypot555676
Node: imaxabs556827
Node: imaxdiv557321
Node: inb558208
Node: index558526
Node: initstate559134
Node: inp559624
Node: inportb559947
Node: inportl560453
Node: inportsb560977
Node: inportsl561352
Node: inportsw561729
Node: inportw562125
Node: inpw562635
Node: insline562961
Node: insque563929
Node: __install_dev_full564588
Node: __install_dev_zero565330
Node: int386566060
Node: int386x566505
Node: int86566971
Node: int86x571108
Node: intdos572104
Node: intdosx572509
Node: intensevideo572941
Node: __internal_readlink573994
Node: _invent_inode575357
Node: ioctl (DOS)576549
Node: ioctl (General description)583842
Node: ioctl (UNIX)584438
Node: _is_cdrom_drive585938
Node: _is_DOS83586771
Node: _is_executable588353
Node: _is_fat32590455
Node: _is_ram_drive591351
Node: _is_remote_drive592233
Node: _is_remote_handle592994
Node: isalnum593794
Node: isalpha594212
Node: isascii594600
Node: isatty594968
Node: isblank595466
Node: iscntrl595940
Node: isdigit596350
Node: isfinite596737
Node: isgraph597485
Node: isgreater597940
Node: isgreaterequal598850
Node: isinf599808
Node: isless600506
Node: islessequal601384
Node: islessgreater602320
Node: islower603295
Node: isnan603698
Node: isnormal604317
Node: isprint605094
Node: ispunct605543
Node: isspace605994
Node: isunordered606465
Node: isupper607085
Node: isxdigit607502
Node: itoa607948
Node: kbhit608884
Node: kill609710
Node: l64a610134
Node: labs611588
Node: lchown611965
Node: ldexp612456
Node: ldiv613258
Node: lfilelength614070
Node: lfind615050
Node: _lfn_gen_short_fname616430
Node: _lfn_get_ftime618933
Node: __libc_termios_exist_queue620648
Node: __libc_termios_init621376
Node: libm621984
Node: link628130
Node: llabs628714
Node: lldiv629116
Node: llockf629981
Node: llrint634137
Node: llrintf635078
Node: llrintl636024
Node: llseek636976
Node: load_npx638347
Node: localeconv639729
Node: localtime642664
Node: localtime_r643499
Node: lock644157
Node: lock64644986
Node: lockf645938
Node: log649605
Node: log10650171
Node: log1p650743
Node: log2651347
Node: longjmp651876
Node: lowvideo652746
Node: lrint653670
Node: lrintf654596
Node: lrintl655524
Node: lsearch656460
Node: lseek658178
Node: lstat659049
Ref: lstat-Footnote-1664743
Node: malldbgdmpfile664965
Node: malldbgdumpfile665635
Node: mallinfo666155
Node: malloc669044
Node: malloc_debug670024
Node: malloc_verify672571
Node: mallocmap673866
Node: mallsethook674554
Node: math_errhandling678822
Node: matherr679774
Node: mblen683913
Node: mbstowcs684588
Node: mbtowc685185
Node: _media_type685872
Node: memalign686819
Node: memccpy687386
Node: memchr688408
Node: memcmp688997
Node: memcpy689497
Node: memicmp690120
Node: memmove690721
Node: memset691369
Node: mkdir692046
Node: mkdtemp692795
Node: mkfifo694196
Node: mknod694612
Node: mkstemp695457
Node: mktemp696953
Node: mktime698384
Node: modf700046
Node: modfl700824
Node: moncontrol701290
Node: _mono_clear702733
Node: _mono_printf703049
Node: _mono_putc703412
Node: monstartup703747
Node: movedata705664
Node: movedatab707355
Node: movedatal707748
Node: movedataw708193
Node: movetext708637
Node: mprotect709688
Node: _my_cs710931
Node: _my_ds711316
Node: _my_ss711699
Node: nan712079
Node: nanf712554
Node: nanl713030
Node: nice713520
Node: normvideo713899
Node: nosound714837
Node: ntohl715116
Node: ntohs715674
Node: open716226
Node: _open720171
Node: opendir721908
Node: outb724095
Node: outp724429
Node: outportb724765
Node: outportl725233
Node: outportsb725706
Node: outportsl726100
Node: outportsw726496
Node: outportw726893
Node: outpw727365
Node: pathconf727709
Node: pause729929
Node: pclose730344
Node: perror731003
Node: pipe731742
Node: popen733759
Node: pow735256
Node: pow10736417
Node: pow2737193
Node: powi737960
Node: _preserve_fncase738775
Node: PRI740366
Node: printf742563
Node: psignal750072
Node: _put_path750862
Node: putc757601
Node: putch758083
Node: putchar759207
Node: putenv759683
Node: puts760786
Node: puttext761280
Node: putw762299
Node: pwrite762998
Node: qsort764648
Node: raise766222
Node: rand766670
Node: rand48768016
Node: random770251
Node: rawclock770712
Node: _rdtsc771194
Node: read772642
Node: _read773436
Node: read_child774047
Node: read_sel_addr774932
Node: readdir775679
Node: readlink777763
Node: readv778834
Node: realloc779957
Node: realpath781509
Node: redir_cmdline_delete783439
Node: redir_cmdline_parse784463
Node: redir_debug_init786730
Node: redir_to_child791710
Node: redir_to_debugger793248
Node: regcomp794753
Node: regerror809542
Node: regexec811955
Node: regfree817907
Node: remove818469
Node: remque819029
Node: _rename819645
Node: rename820967
Node: rewind822627
Node: rewinddir823105
Node: rindex823637
Node: rmdir824243
Node: run_child824744
Node: save_npx827618
Node: sbrk828982
Node: scanf829921
Ref: scanf-Footnote-1842667
Node: SCN842796
Node: Screen Variables844861
Node: ScreenClear846045
Node: ScreenCols846567
Node: ScreenGetChar847283
Node: ScreenGetCursor848340
Node: ScreenMode848928
Node: ScreenPutChar849439
Node: ScreenPutString850134
Node: ScreenRetrieve850930
Node: ScreenRows851687
Node: ScreenSetCursor852309
Node: ScreenUpdate852883
Node: ScreenUpdateLine853453
Node: ScreenVisualBell853994
Node: searchpath854537
Node: seekdir856299
Node: select856976
Node: __set_fd_flags862974
Node: __set_fd_properties863694
Node: _set_screen_lines865769
Node: setbuf867563
Node: setbuffer868461
Node: setcbrk869331
Node: _setcursortype869766
Node: setdate870865
Node: setdisk871354
Node: setenv871853
Node: setftime872970
Node: setgid873795
Node: setgrent874303
Node: setitimer874762
Node: setjmp879008
Node: setlinebuf879883
Node: setlocale880602
Node: setmntent882683
Node: setmode883945
Node: setpgid885375
Node: setpwent885746
Node: setrlimit886156
Node: setsid886662
Node: setstate887091
Node: settime887526
Node: settimeofday888014
Node: setuid888521
Node: setvbuf889031
Node: sigaction890181
Node: sigaddset891808
Node: sigdelset892348
Node: sigemptyset892898
Node: sigfillset893552
Node: sigismember894511
Node: siglongjmp895121
Node: signal895525
Node: signbit905087
Node: __signbitd905883
Node: __signbitf906570
Node: __signbitld907260
Node: sigpending907966
Node: sigprocmask909325
Node: sigsetjmp913139
Node: sin913480
Node: sincos914746
Node: sinh915733
Node: sleep916499
Node: snprintf916984
Node: __solve_dir_symlinks918023
Node: __solve_symlinks919103
Node: sound920227
Node: spawn*920597
Node: sprintf926559
Node: sqrt927107
Node: srand927578
Node: srandom928176
Node: sscanf928706
Node: Stack overflow handler929251
Node: stackavail929835
Node: stat930275
Ref: stat-Footnote-1935929
Node: statfs936150
Node: _status87937590
Node: statvfs938804
Node: _stklen940940
Node: stpcpy941407
Node: stpncpy941823
Node: strcasecmp942395
Node: strcat942929
Node: strchr943403
Node: strcmp944006
Node: strcoll944587
Node: strcpy945217
Node: strcspn945659
Node: strdup946368
Node: strerror946987
Node: strerror_r947563
Node: strftime948780
Node: stricmp954178
Node: strlcat954699
Node: strlcpy956834
Node: strlen958642
Node: strlwr959146
Node: strncasecmp959600
Node: strncat960230
Node: strncmp960723
Node: strncpy961349
Node: strndup961836
Node: strnicmp962547
Node: strnlen963163
Node: strpbrk963869
Node: strrchr964442
Node: strsep964986
Node: strspn965921
Node: strstr966619
Node: strtod967142
Node: strtof969884
Node: strtoimax972615
Node: strtok973640
Node: strtok_r974606
Node: strtol975653
Node: strtold976672
Node: _strtold979355
Node: strtoll981968
Node: strtoul982981
Node: strtoull983596
Node: strtoumax984238
Node: strupr984885
Node: strxfrm985322
Node: swab986010
Node: symlink986635
Node: syms_init987496
Node: syms_line2val988445
Node: syms_listwild989566
Node: syms_module991869
Node: syms_name2val992607
Node: syms_val2line994896
Node: syms_val2name996001
Node: sync997404
Node: sys_errlist998032
Node: sys_nerr998456
Node: sysconf998906
Node: _sysmalloc999805
Node: system1001935
Ref: system-Footnote-11010492
Node: tan1010821
Node: tanh1011496
Node: tcdrain1012089
Node: tcflow1012741
Node: tcflush1013669
Node: tcgetattr1014440
Node: tcgetpgrp1015221
Node: tcsendbreak1015988
Node: tcsetattr1016607
Node: tcsetpgrp1017505
Node: tell1018475
Node: telldir1018895
Node: tempnam1019482
Node: Termios functions1021769
Node: textattr1027398
Node: textbackground1028715
Node: textcolor1029682
Node: textmode1030634
Node: time1032035
Node: times1032497
Node: tmpfile1033506
Node: tmpnam1034122
Node: toascii1035782
Node: _tolower1036245
Node: tolower1036895
Node: _toupper1037418
Node: toupper1038068
Node: _truename1038591
Node: _truename_sfn1041071
Node: truncate1041836
Node: ttyname1042292
Node: tzset1042766
Node: tzsetwall1043323
Node: uclock1043804
Node: umask1046197
Node: uname1046550
Node: ungetc1047603
Node: ungetch1048157
Node: unlink1049183
Node: unlock1050438
Node: unlock641050841
Node: unsetenv1051454
Node: _use_lfn1052351
Node: usleep1055626
Node: utime1056437
Node: utimes1057624
Node: v2loadimage1058916
Node: valloc1061200
Node: varargs1061739
Node: vasnprintf1063804
Node: vasprintf1066191
Node: vdprintf1067629
Node: vfork1068274
Node: vfprintf1068687
Node: vfscanf1069410
Node: vprintf1069904
Node: vscanf1070411
Node: vsnprintf1070910
Node: vsprintf1071976
Node: vsscanf1072587
Node: wait1073109
Node: waitpid1073987
Node: wcstombs1074669
Node: wctomb1075228
Node: wherex1075783
Node: wherey1076698
Node: wild1077608
Node: window1078439
Node: write1079467
Node: _write1081321
Node: write_child1083113
Node: write_sel_addr1084134
Node: writev1084975
Node: xfree1086108
Node: xmalloc1086812
Node: xrealloc1087593
Node: Unimplemented1088450
Node: Function Index1091003
Node: Variable Index1164271
Node: Data Type Index1170411
Node: Concept Index1175828

End Tag Table
