Date: Wed, 1 Apr 1998 13:38:24 +0300 (IDT) From: Eli Zaretskii To: DJ Delorie cc: djgpp-workers AT delorie DOT com Subject: Libc docs changes Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Precedence: bulk Somebody got confused because the docs of the `_dos_XXX' functions doesn't say LFN isn't supported. So here's a bunch of changes that corrects this. Also, the docs for `ioctl' seemed a bit scarce, so I added some more words. *** src/libc/compat/ioctl/ioctl.t~0 Tue Aug 13 03:10:08 1996 --- src/libc/compat/ioctl/ioctl.txh Tue Mar 31 22:58:42 1998 *************** *** 5,45 **** there are lots of different device drivers, no really general description is possible. ! The DJGPP version tries to cope two different flavors of @code{ioctl}, a DOSish ! and a UNIXish way. To distinguish between DOS-like and UNIX-like calls, all ! valid DOS commands have the 3 MSB set to 0, the UNIX command have at least one ! of the 3 MSB set. @node ioctl (DOS), io The DOSish version of @code{ioctl} performs an interrupt 0x21, function 0x44. It takes care of supplying transfer buffers in low address regions, if they are needed. For an exhaustive description of the ! various commands and subcommands, see Ralph Browns interrupt list. It is highly recommended to use only the DOS_* functions listed in @file{sys/ioctl.h}. @subheading Syntax - ioctl(fd, cmd, ... ); @example #include - int main(int argc, char **argv)@{ - char buf[6]; - short *s; ! open(fd,"EMMQXXX0",O_RDONLY); ! mybuf[0] = '\0'; ! s = mybuf; ! ioctl(fd,DOS_SNDDATA,6, (int) &mybuf); ! if(*s ==0x25 )printf("EMM386 >= 4.45\n"); ! mybuf[0]='\x02'; ! ioctl(fd,DOS_SNDDATA,2,(int )&mybuf); ! printf("EMM Version %d.%d\n",(int )mybuf[0],(int) mybuf[1]); ! close(fd); ! @} @end example @subheading Description The parameter @code{fd} must refer to a file descriptor for character device functions, or the number of a block device (usually current=0, A:=1, ...). --- 5,34 ---- there are lots of different device drivers, no really general description is possible. ! The DJGPP version tries to cope with two different flavors of @code{ioctl}, ! a DOSish and a UNIXish way. To distinguish between DOS-like and UNIX-like ! calls, all valid DOS commands have all 3 MSB set to 0, the UNIX command have ! at least one of the 3 MSB set to 1. @node ioctl (DOS), io The DOSish version of @code{ioctl} performs an interrupt 0x21, function 0x44. It takes care of supplying transfer buffers in low address regions, if they are needed. For an exhaustive description of the ! various commands and subcommands, see Ralf Brown's interrupt list. It is highly recommended to use only the DOS_* functions listed in @file{sys/ioctl.h}. + @subheading Syntax @example #include ! int ioctl(int fd, int cmd, ... ); @end example + @subheading Description The parameter @code{fd} must refer to a file descriptor for character device functions, or the number of a block device (usually current=0, A:=1, ...). *************** *** 48,101 **** @table @code @item DOS_GETDEVDATA Get device information. Returns the device information word from @code{DX}. @item DOS_SETDEVDATA Set device information. Returns the new device information word form @code{DX} ! or -1 @item DOS_RCVDATA Read from character device control channel. After @code{cmd} must follow the number of requested bytes to read and a pointer to a buffer. Returns the number ! of bytes actually read or -1 on error. @item DOS_SNDDATA Write to character device control channel. After @code{cmd} must follow the number of bytes to write and a pointer to a buffer holding the data. ! Returns the number of bytes actually written. @item DOS_RCVCTLDATA Read from block device control channel. See @code{DOS_RCVDATA}. @item DOS_SNDCTLDATA Write to block device control channel. See @code{DOS_SNDDATA}. @item DOS_CHKINSTAT Check the input status of a file. Returns 0 if not ready of at EOF, @code{0xff} ! if file is ready. @item DOS_CHKOUTSTAT ! Check the output status of a file. Returns 0 if not ready of at EOF, @code{0xff} ! if file is ready. @item DOS_ISCHANGEABLE Check if a block device is changeable. Returns 0 for removable or 1 for fixed. @item DOS_ISREDIRBLK ! Check if a block device is remote o local. @item DOS_ISREDIRHND ! Check if a file handle refers to a local or remote device. @item DOS_SETRETRY ! Set the sharing retry count. the first extra parameter specifies the pause ! between retries, the second number of retries. @item DOS_GENCHARREQ ! Generic character device request. @item DOS_GENBLKREQ ! Generic block device request. @item DOS_GLDRVMAP ! Get logical drive map. @item DOS_SLDRVMAP ! Set logical drive map. @item DOS_QGIOCTLCAPH Query generic ioctl capability (handle). Test if a handle supports ioctl ! functions beyond those in the standard DOS 3.2 set. @item DOS_QGIOCTLCAPD Query generic ioctl capability (drive). Test if a drive supports ioctl ! functions beyond those in the standard DOS 3.2 set. @end table If your specific device driver requires different commands, they must be or'ed ! together with the flags listed in @file{ioctl.h} to tell the drive about transfer buffers and what to return. @subheading Return Value --- 37,195 ---- @table @code @item DOS_GETDEVDATA Get device information. Returns the device information word from @code{DX}. + The call to @code{ioctl} should look like this: + + @example + int ret_val = ioctl (fd, DOS_GETDEVDATA); + @end example + + For another way of achieving the same effect, see @ref{_get_dev_info}. + @item DOS_SETDEVDATA Set device information. Returns the new device information word form @code{DX} ! or -1. The call to @code{ioctl} should look like this: ! ! @example ! int ret_val = ioctl (fd, DOS_SETDEVDATA, 0, dev_info); ! @end example ! @item DOS_RCVDATA Read from character device control channel. After @code{cmd} must follow the number of requested bytes to read and a pointer to a buffer. Returns the number ! of bytes actually read or -1 on error. The call to @code{ioctl} should ! look like this: ! ! @example ! unsigned char buf[bytes_to_read]; ! int ret_val = ioctl (fd, DOS_RCVDATA, bytes_to_read, &buf); ! @end example ! @item DOS_SNDDATA Write to character device control channel. After @code{cmd} must follow the number of bytes to write and a pointer to a buffer holding the data. ! Returns the number of bytes actually written. An example of a call: ! ! @example ! unsigned char buf[bytes_to_write]; ! int ret_val = ioctl (fd, DOS_SNDDATA, bytes_to_write, &buf); ! @end example ! @item DOS_RCVCTLDATA Read from block device control channel. See @code{DOS_RCVDATA}. + @item DOS_SNDCTLDATA Write to block device control channel. See @code{DOS_SNDDATA}. + @item DOS_CHKINSTAT Check the input status of a file. Returns 0 if not ready of at EOF, @code{0xff} ! if file is ready. Here's an example of how to call: ! ! @example ! int ret_val = ioctl (fd, DOS_CHKINSTAT); ! @end example ! ! A more portable way of doing this is by calling @code{select}. ! @xref{select}. ! @item DOS_CHKOUTSTAT ! Check the output status of a file. Returns 0 if not ready of at EOF, ! @code{0xff} if file is ready. @code{select} (@pxref{select}) is ! another, more portable way of doing the same. ! @item DOS_ISCHANGEABLE Check if a block device is changeable. Returns 0 for removable or 1 for fixed. + An example of a call: + + @example + int ret_val = ioctl (fd, DOS_ISCHANGEABLE); + @end example + + @item DOS_ISREDIRBLK ! Check if a block device is remote o local. The function ! @code{_is_remote_drive} (@pxref{_is_remote_drive}) is another way of ! returning the same info. ! @item DOS_ISREDIRHND ! Check if a file handle refers to a local or remote device. See ! @ref{_is_remote_handle} for another way of doing this. ! @item DOS_SETRETRY ! Set the sharing retry count. The first extra parameter specifies the pause ! between retries, the second number of retries. An example: ! ! @example ! int ret_val = ioctl (fd, DOS_SETRETRY, pause_between_retries, max_retries); ! @end example ! @item DOS_GENCHARREQ ! Generic character device request. Example: ! ! @example ! int ret_val = ioctl (fd, DOS_GENCHARREQ, category_and_function, ! ¶m_block, si_value, di_value, param_block_size); ! @end example ! ! Refer to Ralf Brown's Interrupt List for the details about each function ! and relevant parameter block layout. ! @item DOS_GENBLKREQ ! Generic block device request. Example of the call: ! ! @example ! int ret_val = ioctl (drive_no, DOS_GENBLKREQ, category_and_function, ! ¶m_block, si_value, di_value, param_block_size); ! @end example ! ! Note that instead of the handle, the first argument is the disk drive ! number (0 = default, 1 = A:, etc.). ! @item DOS_GLDRVMAP ! Get logical drive map. A call like the following: ! ! @example ! int ret_val = ioctl (drive_no, DOS_GLDRVMAP); ! @end example ! ! @noindent ! will return 0 if the block device has only one logical drive assigned, ! or a number in the range 1..26 which is the last drive numer used to ! reference that drive (1 = A:, etc.). Thus, on a machine which has a ! single floppy drive, calling @code{ioctl (1, DOS_GLDRVMAP);} will return ! 2 if the floppy was last refered to as B:. This function and the next ! one can be used together to prevent DOS from popping the ugly prompt ! saying "Insert diskette for drive B: and press any key when ready". ! @item DOS_SLDRVMAP ! Set logical drive map. For example, a call like this: ! ! @example ! ioctl (1, DOS_SLDRVMAP); ! @end example ! ! @noindent ! will cause drive A: to be mapped to drive B:. ! @item DOS_QGIOCTLCAPH Query generic ioctl capability (handle). Test if a handle supports ioctl ! functions beyond those in the standard DOS 3.2 set. Call like this: ! ! @example ! int ret_val = ioctl (fd, DOS_QGIOCTLCAPH, category_and_function); ! @end example ! ! This will return zero if the specified IOCTL function is supported, 1 if ! not. ! @item DOS_QGIOCTLCAPD Query generic ioctl capability (drive). Test if a drive supports ioctl ! functions beyond those in the standard DOS 3.2 set. Used same as ! DOS_QGIOCTLCAPH, but the first argument is a drive number (0 = default, ! 1 = A:, etc.), not a handle. @end table If your specific device driver requires different commands, they must be or'ed ! together with the flags listed in @code{} to tell the drive about transfer buffers and what to return. @subheading Return Value *************** *** 144,149 **** --- 238,263 ---- 5-0 drive number (0 = A:) @end table + + @subheading Example + + @example + #include + int main(int argc, char **argv)@{ + char buf[6]; + short *s; + + open(fd,"EMMQXXX0",O_RDONLY); + mybuf[0] = '\0'; + s = mybuf; + ioctl(fd,DOS_SNDDATA,6, (int) &mybuf); + if(*s ==0x25 )printf("EMM386 >= 4.45\n"); + mybuf[0]='\x02'; + ioctl(fd,DOS_SNDDATA,2,(int )&mybuf); + printf("EMM Version %d.%d\n",(int )mybuf[0],(int) mybuf[1]); + close(fd); + @} + @end example @node ioctl (UNIX), io The UNIX version first checks if an FSE handler is associated to the file *** src/libc/dos/compat/d_findf.t~0 Sun Aug 31 19:02:14 1997 --- src/libc/dos/compat/d_findf.txh Tue Mar 31 22:03:52 1998 *************** *** 49,54 **** --- 49,59 ---- @xref{_dos_findnext}. + This function does not support long filenames, even on systems where the + LFN API (@pxref{_use_lfn, LFN}) is available. For LFN-aware functions + with similar functionality see @ref{findfirst}, and @ref{findnext}. + Also see @ref{opendir}, and @ref{readdir}, which are Posix-standard. + @subheading Return Value Zero if a match is found, DOS error code if not found (and sets @var{errno}). *************** *** 56,64 **** @subheading Example @example ! struct find_t f; /* in */ ! if ( !_dos_findfirst("*.DAT", &f, _A_ARCH | _A_RDONLY) ) @{ do @{ --- 61,71 ---- @subheading Example @example ! #include ! ! struct find_t f; ! if ( !_dos_findfirst("*.DAT", _A_ARCH | _A_RDONLY), &f ) @{ do @{ *** src/libc/dos/compat/d_findn.t~0 Mon Oct 9 06:00:00 1995 --- src/libc/dos/compat/d_findn.txh Tue Mar 31 21:38:14 1998 *************** *** 13,18 **** --- 13,23 ---- @xref{_dos_findfirst}. + This function does not support long filenames, even on systems where the + LFN API (@pxref{_use_lfn, LFN}) is available. For LFN-aware functions + with similar functionality see @ref{findfirst}, and @ref{findnext}. + Also see @ref{opendir}, and @ref{readdir}, which are Posix-standard. + @subheading Return Value Zero if a match is found, DOS error code if not found (and sets @var{errno}). *** src/libc/dos/compat/d_getfa.t~0 Sun Aug 31 20:13:18 1997 --- src/libc/dos/compat/d_getfa.txh Tue Mar 31 21:38:34 1998 *************** *** 46,51 **** --- 46,56 ---- @xref{_dos_setfileattr}. + This function does not support long filenames, even on systems where the + LFN API (@pxref{_use_lfn, LFN}) is available. For LFN-aware functions + with similar functionality see @ref{_chmod}. Also see @ref{chmod}, + @ref{access}, and @ref{stat}, which are Posix-standard. + @subheading Return Value Returns with 0 if successful and DOS error value on error (and sets *** src/libc/dos/compat/d_open.t~0 Mon Oct 9 06:00:00 1995 --- src/libc/dos/compat/d_open.txh Tue Mar 31 21:38:58 1998 *************** *** 70,75 **** --- 70,81 ---- @xref{_dos_creat}. @xref{_dos_creatnew}. @xref{_dos_read}. @xref{_dos_write}. @xref{_dos_close} + This function does not support long filenames, even on systems where the + LFN API (@pxref{_use_lfn, LFN}) is available. For LFN-aware functions + with similar functionality see @ref{_open}, @ref{_creat}, and + @ref{_creatnew}. Also see @ref{open}, and @ref{creat}, which are + Posix-standard. + @subheading Return Value Returns 0 if successful or DOS error code on error (and sets *** src/libc/dos/compat/d_creat.t~0 Mon Oct 9 06:00:00 1995 --- src/libc/dos/compat/d_creat.txh Tue Mar 31 21:37:54 1998 *************** *** 42,47 **** --- 42,52 ---- @xref{_dos_open}. @xref{_dos_creatnew}. @xref{_dos_read}. @xref{_dos_write}. @xref{_dos_close} + This function does not support long filenames, even on systems where the + LFN API (@pxref{_use_lfn, LFN}) is available. For LFN-aware functions + with similar functionality see @ref{_creat}, and @ref{_creatnew}. Also + see @ref{creat}, and @ref{open}, which are Posix-standard. + @subheading Return Value Returns 0 if successful or DOS error code on error (and sets @var{errno}) *** src/libc/dos/compat/d_creatn.t~0 Mon Oct 9 06:00:00 1995 --- src/libc/dos/compat/d_creatn.txh Tue Mar 31 21:37:44 1998 *************** *** 42,47 **** --- 42,52 ---- @xref{_dos_open}. @xref{_dos_creat}. @xref{_dos_read}. @xref{_dos_write}. @xref{_dos_close} + This function does not support long filenames, even on systems where the + LFN API (@pxref{_use_lfn, LFN}) is available. For LFN-aware functions + with similar functionality see @ref{_creatnew}, and @ref{_creat}. Also + see @ref{creat}, and @ref{open}, which are Posix-standard. + @subheading Return Value Returns 0 if successful or DOS error code on error (and sets @var{errno}). *** src/libc/dos/compat/d_getftm.t~0 Mon Oct 9 06:00:00 1995 --- src/libc/dos/compat/d_getftm.txh Tue Mar 31 22:02:08 1998 *************** *** 39,44 **** --- 39,49 ---- @xref{_dos_setftime}. + This function cannot be used to return last access and creation date and + time, even on systems where the LFN API (@pxref{_use_lfn, LFN}) is + available. See @ref{_lfn_get_ftime}, for a function that can be used to + get the other two times. Also see @ref{fstat}, which is Posix-standard. + @subheading Return Value Returns 0 if successful and return DOS error on error (and sets *** src/libc/dos/compat/d_setfa.t~0 Sun Aug 31 20:13:18 1997 --- src/libc/dos/compat/d_setfa.txh Tue Mar 31 21:32:24 1998 *************** *** 46,51 **** --- 46,56 ---- @xref{_dos_getfileattr}. + This function does not support long filenames, even on systems where the + LFN API (@pxref{_use_lfn, LFN}) is available. For LFN-aware functions + with similar functionality see @ref{_chmod}. Also see @ref{chmod}, which + is Posix-standard. + @subheading Return Value Returns with 0 if successful and DOS error value on error (and sets *** src/libc/dos/dir/findfirs.t~0 Mon Jul 10 05:40:12 1995 --- src/libc/dos/dir/findfirs.txh Tue Mar 31 21:58:40 1998 *************** *** 48,63 **** @code{FA_LABEL}, you would get all subdirectories, the volume label, and any file that is neither read-only or modified. ! The results of the search are stored in @var{ffblk}: @example struct ffblk @{ ! char ff_reserved[21]; /* 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[16]; /* name of file as ASCIIZ string */ @} @end example --- 48,73 ---- @code{FA_LABEL}, you would get all subdirectories, the volume label, and any file that is neither read-only or modified. ! This function supports long file names. ! ! The results of the search are stored in @var{ffblk}, which is extended ! when the LFN API (@pxref{_use_lfn, LFN}) is supported. Fields marked ! LFN are only valid if the @code{lfn_magic} member is set to "LFN32". @example struct ffblk @{ ! char lfn_magic[6]; /* LFN: the magic "LFN32" signature */ ! short lfn_handle; /* LFN: the handle used by findfirst/findnext */ ! unsigned short lfn_ctime; /* LFN: file creation time */ ! unsigned short lfn_cdate; /* LFN: file creation date */ ! unsigned short lfn_atime; /* LFN: file last access time (usually 0) */ ! unsigned short lfn_adate; /* LFN: file last access date */ ! char ff_reserved[5]; /* used to hold the state of the search */ unsigned char ff_attrib; /* actual attributes of the file found */ unsigned short ff_ftime; /* hours:5, minutes:6, (seconds/2):5 */ unsigned short ff_fdate; /* (year-1980):7, month:4, day:5 */ unsigned long ff_fsize; /* size of file */ ! char ff_name[260]; /* name of file as ASCIIZ string */ @} @end example *** src/libc/dos/io/_chmod.t~0 Mon Aug 28 00:33:24 1995 --- src/libc/dos/io/_chmod.txh Tue Mar 31 21:42:22 1998 *************** *** 29,34 **** --- 29,38 ---- ..1..... Archive xx...... Reserved (used by some network redirectors) @end example + + On platforms where the LFN API (@pxref{_use_lfn, LFN}) is available, + @code{_chmod} calls function 0x7143 of Interrupt 21h, to support long + file names. @subheading Return Value *** src/libc/dos/io/_creat.t~0 Sun Aug 31 17:12:00 1997 --- src/libc/dos/io/_creat.txh Tue Mar 31 21:43:56 1998 *************** *** 14,19 **** --- 14,23 ---- be hooked by the @xref{File System Extensions}. If you don't want this you should use @xref{_dos_creat} or @xref{_dos_creatnew}. + On platforms where the LFN API (@pxref{_use_lfn, LFN}) is available, + @code{_creat} calls function 0x716C of Interrupt 21h, to support long + file names. + @subheading Return Value The new file descriptor, else -1 on error.