harbour-core/harbour/doc/en/file.txt

/*
 * $Id$
 */

/*
 * The following parts are Copyright of the individual authors.
 * www - http://harbour-project.org
 *
 * Copyright 2000 Chen Kedem <niki@actcom.co.il>
 *    Documentation for: __TYPEFILE(), TYPE
 *
 * Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
 *    Documentation for: FOPEN(), FCLOSE(), FWRITE(), FSEEK(), FREAD(), FILE(),
 *                       FREADSTR(), FRENAME(), FERROR(), RENAME, ERASE, CURDIR(),
 *                       DIRMAKE(), DIRCHANGE(), ISDISK(), DIRREMOVE(), DISKCHANGE(),
 *                       DIRCHANGE()
 *
 * Copyright 2000 David G. Holm <Harbour@SpaceMoose.com>
 *    Documentation for: HB_FEOF()
 *
 * See COPYING for licensing terms.
 *
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      FOPEN()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Open a file.
 *  $SYNTAX$
 *      FOPEN( <cFile>, [<nMode>] ) --> nHandle
 *  $ARGUMENTS$
 *      <cFile> Name of file to open.
 *
 *      <nMode> Dos file open mode.
 *  $RETURNS$
 *      <nHandle> A file handle.
 *  $DESCRIPTION$
 *      This function opens a file expressed as <cFile> and returns a
 *      file handle to be used with other low-level file functions. The
 *      value of <nMode> represents the status of the file to be opened;
 *      the default value is 0. The file open modes are as follows:

 *  <table>
 *       nMode   fileio.ch      Meaning
 *
 *       0       FO_READ        Read only
 *       1       FO_WRITE       Write only
 *       2       FO_READWRITE   Read/write
 *       16      FO_EXCLUSIVE   Exclusive read only
 *       32      FO_DENYWRITE   Prevent others from writing
 *       48      FO_DENYREAD    Deny read only
 *       64      FO_DENYNONE    Not deny, Let to others Read / Write
 *       64      FO_SHARED      same as FO_DENYNONE
 *  </table>
 *
 *      If there is an error in opening a file, a -1 will be returned by
 *      the function. Files handles may be in the range of 0 to 65535. The
 *      status of the SET DEFAULT TO and SET PATH TO commands has no effect
 *      on this function. Directory names and paths must be specified along
 *      with the file that is to be opened.
 *
 *      If an error has occured, see the returns values from FERROR() for
 *      possible reasons for the error.
 *  $EXAMPLES$
 *
 *      IF (nH:=FOPEN('x.txt',66) < 0
 *         ? 'File can't be opened'
 *      ENDIF
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $FILES$
 *      Library is rtl
 *      Header  is fileio.ch
 *  $SEEALSO$
 *      FCREATE(),FERROR(),FCLOSE()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      FCREATE()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Creates a file.
 *  $SYNTAX$
 *      FCREATE( <cFile>, [<nAttribute>] ) --> nHandle
 *  $ARGUMENTS$
 *      <cFile> is the name of the file to create.
 *
 *      <nAttribute> Numeric code for the file attributes.
 *  $RETURNS$
 *      <nHandle>  Numeric file handle to be used in other operations.
 *  $DESCRIPTION$
 *      This function creates a new file with a filename of <cFile>. The
 *      default value of <nAttribute> is 0 and is used to set the
 *      attribute byte for the file being created by this function.
 *      The return value will be a file handle that is associated
 *      with the new file. This number will be between zero to 65,535,
 *      inclusive. If an error occurs, the return value of this function
 *      will be -1.
 *
 *      If the file <cFile> already exists, the existing file will be
 *      truncated to a file length of 0 bytes.

 *      If specified, the following table shows the value for <nAttribute>
 *      and their related meaning to the file <cFile> being created by
 *      this function.
 *
 *  <table>
 *       <nAttribute>   fileio.ch     Meaning
 *
 *       0              FC_NORMAL     Normal/Default,Read/Write
 *       1              FC_READONLY   Read-only file attribute is set
 *       2              FC_HIDDEN     Hidden,Excluded from normal DIR search
 *       4              FC_SYSTEM     Create,Excluded from normal DIR search
 *  </table>
 *  $EXAMPLES$
 *      IF (nh:=FCREATE("test.txt") <0
 *          ? "Cannot create file"
 *      ENDIF
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $FILES$
 *      Library is rtl
 *      Header is fileio.ch
 *  $SEEALSO$
 *      FCLOSE(),FOPEN(),FWRITE(),FREAD(),FERROR()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      FREAD()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Reads a specified number of bytes from a file.
 *  $SYNTAX$
 *      FREAD( <nHandle>, @<cBuffer>, <nBytes> ) --> nBytes
 *  $ARGUMENTS$
 *      <nHandle>     Dos file handle

 *      <cBuffer>  Character expression passed by reference.

 *      <nBytes>      Number of bytes to read.
 *  $RETURNS$
 *      <nBytes> the number of bytes successfully read from the file.
 *      <nHandle>
 *  $DESCRIPTION$
 *      This function reads the characters from a file whose file handle
 *      is <nHandle> into a character memory variable expressed as <cBuffer>.
 *      The function returns the number of bytes successfully read into
 *      <cBuffer>.

 *      The value of <nHandle> is obtained from either a call to the FOPEN()
 *      or the FCREATE() function.

 *      The <cBuffer> expression is passed by reference and must be defined
 *      before this function is called. It also must be at least the same
 *      length as <nBytes>.

 *      <nBytes> is the number of bytes to read, starting at the current
 *      file pointer position. If this function is successful in reading
 *      the characters from the file, the length of <cBuffer> or the number
 *      of bytes specified in <nBytes> will be the value returned. The current
 *      file pointer advances the number of bytes read with each successive
 *      read. The return value is the number of bytes successfully read
 *      from the file. If a 0 is returned, or if the number of
 *      bytes read matches neither the length of <cBuffer> nor the specified
 *      value in <nBytes> an end-of-file condition has been reached.
 *  $EXAMPLES$
 *      cBuffer:=SPACE(500)
 *      IF (nH:=FOPEN('x.txt'))>0
 *         FREAD(nH,@cBuffer,500)
 *         ? cbuffer
 *      ENDIF
 *      FCLOSE(nH)
 *  $STATUS$
 *     R
 *  $COMPLIANCE$
 *     C
 *  $PLATFORMS$
 *     All(64K)
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *     BIN2I(),BIN2L(),BIN2W(),FERROR(),FWRITE()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      FWRITE()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Writes characters to a file.
 *  $SYNTAX$
 *     FWRITE( <nHandle>, <cBuffer>, [<nBytes>] ) --> nBytesWritten
 *  $ARGUMENTS$
 *     <nHandle>  DOS file handle number.

 *     <cBuffer>  Character expression to be written.

 *     <nBytes>   The number of bytes to write.
 *  $RETURNS$
 *      <nBytesWritten> the number of bytes successfully written.
 *  $DESCRIPTION$
 *      This function writes the contents of <cBuffer> to the file designated
 *      by its file handle <nHandle>. If used, <nBytes> is the number of
 *      bytes in <cBuffer> to write.

 *      The returned value is the number of bytes successfully written to the
 *      DOS file. If the returned value is 0, an error has occurred (unless
 *      this is intended). A successful write occurs when the number returned
 *      by FWRITE() is equal to either LEN( <cBuffer>) or <nBytes>.

 *      The value of <cBuffer> is the string or variable to be written to the
 *      open DOS file <nHandle>.

 *      The value of <nBytes> is the number of bytes to write out to the file.
 *      The disk write begins with the current file position in <nHandle>. If
 *      this variable is not used, the entire contents of <cBuffer> is written
 *      to the file.
 *      To truncate a file, a call of FWRITE( nHandle, "", 0 ) is needed.
 *  $EXAMPLES$
 *      nHandle := FCREATE( "x.txt" )
 *      FOR X := 1 TO 10
 *        FWRITE( nHandle, STR( x ) )
 *      NEXT
 *      FCLOSE( nHandle )
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All(64K)
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      FCLOSE(), FCREATE(), FERROR(), FOPEN(), I2BIN(), L2BIN()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      FERROR()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Reports the error status of low-level file functions
 *  $SYNTAX$
 *      FERROR() --> <nErrorCode>
 *  $RETURNS$
 *      <nErrorCode> Value of the DOS error last encountered by a
 *      low-level file function.
 *
 *      FERROR() Return Values
 *
 *      <table>
 *       Error          Meaning
 *
 *       0              Successful
 *       2              File not found
 *       3              Path not found
 *       4              Too many files open
 *       5              Access denied
 *       6              Invalid handle
 *       8              Insufficient memory
 *       15             Invalid drive specified
 *       19             Attempted to write to a write-protected disk
 *       21             Drive not ready
 *       23             Data CRC error
 *       29             Write fault
 *       30             Read fault
 *       32             Sharing violation
 *       33             Lock Violation
 *  </table>
 *  $DESCRIPTION$
 *      After every low-level file function,this function will return
 *      a value that provides additional informationon the status of
 *      the last low-level file functions's performance. If the FERROR()
 *      function returns a 0, no error was detected. Below is a table
 *      of possibles values returned by the FERROR() function.
 *  $EXAMPLES$
 *      #include "fileio.ch"
 *      //
 *      nHandle := FCREATE( "temp.txt", FC_NORMAL )
 *      IF FERROR() != 0
 *         ? "Cannot create file, DOS error ", FERROR()
 *      ENDIF
 *  $STATUS$
 *     R
 *  $COMPLIANCE$
 *     C
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *     FCLOSE(),FERASE(),FOPEN(),FWRITE()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      FCLOSE()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *     Closes an open file
 *  $SYNTAX$
 *     FCLOSE( <nHandle> ) --> <lSuccess>
 *  $ARGUMENTS$
 *     <nHandle> DOS file handle
 *  $RETURNS$
 *     <lSuccess>  Logical TRUE (.T.) or FALSE (.F.)
 *  $DESCRIPTION$
 *     This function closes an open file with a dos file handle
 *     of <nHandle> and writes the associated DOS buffer to the
 *     disk. The <nHandle> value is derived from the FCREATE()
 *     or FOPEN() function.
 *  $EXAMPLES$
 *     nHandle:=FOPEN('x.txt')
 *     ? FSEEK(nHandle, 0, 2)
 *     FCLOSE(nHandle)
 *  $STATUS$
 *     R
 *  $COMPLIANCE$
 *     C
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *     FOPEN(),FCREATE(),FREAD(),FWRITE(),FERROR()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      FERASE()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Erase a file from disk
 *  $SYNTAX$
 *      FERASE( <cFile> ) --> nSuccess
 *  $ARGUMENTS$
 *      <cFile> Name of file to erase.
 *  $RETURNS$
 *      <nSuccess> 0 if successful, -1 if not
 *  $DESCRIPTION$
 *      This function deletes the file specified in <cFile> from the disk.
 *      No extensions are assumed. The drive and path my be included in
 *      <cFile>; neither the SET DEFAULT not the SET PATH command controls
 *      the performance of this function. If the drive or path is not used,
 *      the function will look for the file only on the currently selected
 *      direcytory on the logged drive.
 *
 *      If the function is able to successfully delete the file from the
 *      disk, the value of the function will be 0; otherwise a -1 will
 *      be returned. If not successfu, aditional information may be
 *      obtained by calling the FERROR() function.
 *
 *      Note: Any file to be removed by FERASE() must still be closed.
 *
 *  $EXAMPLES$
 *      IF FERASE("test.txt")==0
 *          ? "File successfully erased"
 *      ELSE
 *          ? "File can not be deleted"
 *      ENDIF
 *  $STATUS$
 *     R
 *  $COMPLIANCE$
 *     C
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *     FERROR(),FRENAME()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      FRENAME()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Renames a file
 *  $SYNTAX$
 *      FRENAME( <cOldFile>, <cNewFile> ) --> nSuccess
 *  $ARGUMENTS$
 *     <cOldFile> Old filenarne to he changed

 *     <cNewFile> New filename
 *  $RETURNS$
 *     <nSuccess> If sucessful, a 0 will he returned otherwise,
 *     a -1 will be returned.
 *  $DESCRIPTION$
 *      This function renames the specified file <cOldFile> to <cNewFile>.
 *      A filename and/or directory name may be specified for either para-
 *      meter. However, if a path is supplied as part of <cNewFile> and
 *      this path is different from either the path specified in <cOldFile>
 *      or (if none is used) the current drive and directory, the function
 *      will not execute successfully.

 *      Neither parameter is subject to the control of the SET PATH TO or
 *      SET DEFAULT TO commands. In attempting to locate the file to be
 *      renamed, this function will search the default drive and directory
 *      or the drive and path specified in <cOldFile>. It will not search
 *      directories named by the SET PATH TO and SET DEFAULT TO commands
 *      or by the DOS PATH statement.

 *      If the file specified in <cNewFile> exists or the file is open,
 *      the function will be unable to rename the file. If the function
 *      is unable to complete its operation,it will return a value of -1.
 *      If it is able to rename the file, the return value for the function
 *      will be 0. A call to FERROR() function will give additional infor-
 *      mation about any error found.
 *  $EXAMPLES$
 *      nResult := FRENAME( "x.txt", "x1.txt" )
 *      IF nResult < 0
 *         ? "File could not be renamed."
 *      ENDIF
 *  $STATUS$
 *     R
 *  $COMPLIANCE$
 *     C
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *     ERASE,FERASE(),FERROR(),FILE(),RENAME
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      FSEEK()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Positions the file pointer in a file.
 *  $SYNTAX$
 *      FSEEK( <nHandle>, <nOffset>, [<nOrigin>] ) --> nPosition
 *  $ARGUMENTS$
 *     <nHandle> DOS file handle.

 *     <nOffset> The number of bytes to move.

 *     <nOrigin> The relative position in the file.
 *  $RETURNS$
 *      <nPosition> the current position relative to begin-of-file
 *  $DESCRIPTION$
 *      This function sets the file pointer in the file whose DOS file
 *      handle is <nHandle> and moves the file pointer by <expN2> bytes
 *      from the file position designated by <nOrigin>. The returned value
 *      is the relative position of the file pointer to the beginning-of-file
 *      marker once the operation has been completed.

 *      <nHandle> is the file handle number. It is obtained from the FOPEN()
 *      or FCREATE() function.

 *      The value of <nOffSet> is the number of bytes to move the file pointer
 *      from the position determined by <nOrigin>. The value of <nOffset> may
 *      be a negative number, suggesting backward movement.

 *      The value of <nOrigin> designates the starting point from which the
 *      file pointer should he moved, as shown in the following table:

 *      <table>
 *       <nOrigin>   fileio.ch     File position
 *
 *       0           FS_SET        Beginning of file
 *       1           FS_RELATIVE   Current file pointer position
 *       2           FS_END        End of file
 *      </table>
 *
 *      If a value is not provided for <nOrigin>, it defaults to 0 and
 *      moves the file pointer from the beginning of the file.
 *  $EXAMPLES$
 *      // here is a function that read one text line from an open file
 *
 *      // nH = file handle obtained from FOPEN()
 *      // cB = a string buffer passed-by-reference to hold the result
 *      // nMaxLine = maximum number of bytes to read
 *
 *      #define EOL HB_OSNEWLINE()
 *      FUNCTION FREADln( nH, cB, nMaxLine )
 *      LOCAL cLine, nSavePos, nEol, nNumRead
 *      cLine := space( nMaxLine )
 *      cB := ''
 *      nSavePos := FSEEK( nH, 0, FS_RELATIVE )
 *      nNumRead := FREAD( nH, @cLine, nMaxLine )
 *      IF ( nEol := AT( EOL, substr( cLine, 1, nNumRead ) ) ) == 0
 *        cB := cLine
 *      ELSE
 *        cB := SUBSTR( cLine, 1, nEol - 1 )
 *        FSEEK( nH, nSavePos + nEol + 1, FS_SET )
 *      ENDIF
 *      RETURN nNumRead != 0
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $FILES$
 *      Library is rtl
 *      Header is fileio.ch
 *  $SEEALSO$
 *      FCREATE(),FERROR(),FOPEN(),FREAD(),FREADSTR(),FWRITE()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      FILE()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Tests for the existence of file(s)
 *  $SYNTAX$
 *      FILE( <cFileSpec> ) --> lExists
 *  $ARGUMENTS$
 *      <cFileSpec> Dos Skeleton or file name to find.
 *  $RETURNS$
 *      <lExists> a logical true (.T.) if the file exists or logical
 *      false (.F.).
 *  $DESCRIPTION$
 *      This function return a logical true (.T.) if the given filename
 *      <cFileSpec> exist.

 *      Dos skeletons symbols may be used in the filename in <cFileSpec>,
 *      as may the drive and/or path name. If a path is not explicity
 *      specified, FILE() will look for the file in the SET DEFAULT path,
 *      then in each SET PATH path, until the file is found or there are
 *      no more paths to search. The DOS PATH is never searched and the
 *      current drive/directory is only searched if SET DEFAULT is blank.
 *  $EXAMPLES$
 *      ? file('C:\harbour\doc\compiler.txt")
 *      ? file('C:/harbour/doc/subcodes.txt")
 *  $STATUS$
 *      S (wild card support is missing)
 *  $COMPLIANCE$
 *      C
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      SET DEFAULT,SET PATH,SET()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      FREADSTR()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Reads a string from a file.
 *  $SYNTAX$
 *      FREADSTR(<nHandle>, <nBytes>) --> cString
 *  $ARGUMENTS$
 *      <nHandle> DOS file handle number.
 *
 *      <nBytes>  Number of bytes to read.
 *  $RETURNS$
 *      <cString> an characted expression
 *  $DESCRIPTION$
 *      This function returns a character string of <nBytes> bytes from a
 *      file whose DOS file handle is <nHandle>.

 *      The value of the file handle <nHandle> is obtained from either the
 *      FOPEN() or FCREATE() functions.

 *      The value of <nBytes> is the number of bytes to read from the file.
 *      The returned string will be the number of characters specified in
 *      <nBytes> or the number of bytes read before an end-of-file charac-
 *      ter (ASCII 26) is found.

 *      NOTE  This function is similar to the FREAD() function, except that
 *      it will not     read binary characters that may he required as part of
 *      a header of a file construct. Characters Such as CHR(0) and CHR(26)
 *      may keep this   function from performing its intended operation. In this
 *      event, the FREAD() function should he used in place of the FREADSTR()
 *      function.
 *  $EXAMPLES$
 *      IF ( nH := FOPEN("x.txt") ) > 0
 *         cStr := Freadstr(nH,100)
 *         ? cStr
 *      ENDIF
 *      FCLOSE(nH)
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *     C
 *  $PLATFORMS$
 *     All(64K)
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      BIN2I(),BIN2L(),BIN2W(),FERROR(),FREAD(),FSEEK()
 *  $END$
 */

/* HARBOUR COMMANDS */

/*  $DOC$
 *  $TEMPLATE$
 *      Command
 *  $NAME$
 *      RENAME
 *  $CATEGORY$
 *      Command
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Changes the name of a specified file
 *  $SYNTAX$
 *     RENAME <cOldFile> TO <cNewFile>
 *  $ARGUMENTS$
 *      <cOldFile> Old filename

 *      <cNewFile> New Filename
 *  $DESCRIPTION$
 *      This command changes the name of <cOldFile> to <cNewFile>. Both
 *      <cOldFile> and <cNewFile> must include a file extension. This command
 *      if not affected by the SET PATH TO or SET DEFAULT TO commands;drive
 *      and directoy designaters must be specified if either file is in a
 *      directory other then the default drive and directory.
 *
 *      If <cNewFile> id currently open or if it previously exists, this
 *      command will not perform the desired operation.
 *  $EXAMPLES$
 *      RENAME C:\autoexec.bat TO C:\autoexec.old
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      CURDIR(),ERASE,FILE(),FERASE(),FRENAME()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Command
 *  $NAME$
 *      ERASE
 *  $CATEGORY$
 *      Command
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Remove a file from disk
 *  $SYNTAX$
 *      ERASE <xcFile>
 *  $ARGUMENTS$
 *      <xcFile> Name of file to remove
 *  $DESCRIPTION$
 *      This command removes a file from the disk. The use of a drive,directo-
 *      ry, and wild-card skeleton operator is allowed for the root of the
 *      filename. The file extension is required. The SET DEFAULT and SET PATH
 *      commands do not affect this command.

 *      The file must be considered closed by the operating system before it
 *      may be deleted.
 *  $EXAMPLES$
 *      ERASE C:\autoexec.bat
 *      ERASE C:/temp/read.txt
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $SEEALSO$
 *      CURDIR(), FILE(), FERASE(), DELETE FILE
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Command
 *  $NAME$
 *      DELETE FILE
 *  $CATEGORY$
 *      Command
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Remove a file from disk
 *  $SYNTAX$
 *      DELETE FILE <xcFile>
 *  $ARGUMENTS$
 *      <xcFile> Name of file to remove
 *  $DESCRIPTION$
 *      This command removes a file from the disk. The use of a drive,directo-
 *      ry,and wild-card skeleton operator is allowed for the root of the
 *      filename. The file extension is required. The SET DEFAULT and SET PATH
 *      commands do not affect this command.

 *      The file must be considered closed by the operating system before it
 *      may be deleted.
 *  $EXAMPLES$
 *      ERASE C:\autoexec.bat
 *      ERASE C:/temp/read.txt
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $SEEALSO$
 *      CURDIR(), FILE(), FERASE(), ERASE
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      __TYPEFILE()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Terminal
 *  $ONELINER$
 *      Show the content of a file on the console and/or printer
 *  $SYNTAX$
 *      __TYPEFILE( <cFile>, [<lPrint>] ) --> NIL
 *  $ARGUMENTS$
 *      <cFile> is a name of the file to display. If the file have an
 *      extension, it must be specified (there is no default value).
 *
 *      <lPrint> is an optional logical value that specifies whether the
 *      output should go only to the screen (.F.) or to both the screen and
 *      printer (.T.), the default is (.F.).
 *  $RETURNS$
 *      __TYPEFILE() always return NIL.
 *  $DESCRIPTION$
 *      __TYPEFILE() function type the content of a text file on the screen
 *      with an option to send this information also to the printer. The
 *      file is displayed as is without any headings or formating.
 *
 *      If <cFile> contain no path, __TYPEFILE() try to find the file first
 *      in the SET DEFAULT directory and then in search all of the SET PATH
 *      directories. If <cFile> can not be found a run-time error occur.
 *
 *      Use SET CONSOLE OFF to suppress screen output.
 *      You can pause the output using Ctrl-S, press any key to resume.
 *
 *      __TYPEFILE() function is used in the preprocessing of the TYPE
 *      command.
 *  $EXAMPLES$
 *      The following examples assume a file name mytext.dat exist in all
 *      specified paths, a run-time error would displayed if it does not
 *
 *      // display mytext.dat file on screen
 *      __TYPEFILE( "mytext.dat" )
 *
 *      // display mytext.dat file on screen and printer
 *      __TYPEFILE( "mytext.dat", .T. )
 *
 *      // display mytext.dat file on printer only
 *      SET CONSOLE OFF
 *      __TYPEFILE( "mytext.dat", .T. )
 *      SET CONSOLE ON
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      COPY FILE,SET DEFAULT,SET PATH,SET PRINTER,TYPE
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Command
 *  $NAME$
 *      TYPE
 *  $CATEGORY$
 *      Command
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Show the content of a file on the console, printer or file
 *  $SYNTAX$
 *      TYPE <xcFile> [TO PRINTER] [TO FILE <xcDestFile>]
 *  $ARGUMENTS$
 *      <xcFile> is a name of the file to display. If the file have an
 *      extension, it must be specified (there is no default value).
 *      It can be specified as literal file name or as a character
 *      expression enclosed in parentheses.
 *
 *      TO PRINTER is an optional keyword that specifies that the output
 *      should go to both the screen and printer.
 *
 *      TO FILE <xcDestFile> copy the source <xcFile> also to a file. If no
 *      extension is given (.txt) is added to the output file name.
 *      <xcDestFile> can be specified as literal file name or as a character
 *      expression enclosed in parentheses.
 *  $DESCRIPTION$
 *      TYPE command type the content of a text file on the screen
 *      with an option to send this information also to the printer or to
 *      an alternate file. The file is displayed as is without any headings
 *      or formating.
 *
 *      If <xcFile> contain no path, TYPE try to find the file first in the
 *      SET DEFAULT directory and then in search all of the SET PATH
 *      directories. If <xcFile> can not be found a run-time error occur.
 *
 *      If <xcDestFile> contain no path it is created in the SET DEFAULT
 *      directory.
 *
 *      Use SET CONSOLE OFF to suppress screen output.
 *      You can pause the output using Ctrl-S, press any key to resume.
 *  $EXAMPLES$
 *      The following examples assume a file name mytext.dat exist in all
 *      specified paths, a run-time error would displayed if it does not
 *
 *      // display mytext.dat file on screen
 *      TYPE mytext.dat
 *
 *      // display mytext.dat file on screen and printer
 *      TYPE mytext.dat TO PRINTER
 *
 *      // display mytext.dat file on printer only
 *      SET CONSOLE OFF
 *      TYPE mytext.dat TO PRINTER
 *      SET CONSOLE ON
 *
 *      // display mytext.dat file on screen and into a file myreport.txt
 *      TYPE mytext.dat TO FILE MyReport
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $SEEALSO$
 *      COPY FILE,SET DEFAULT,SET PATH,SET PRINTER,__TYPEFILE()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      CURDIR()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Returns the current OS directory name.
 *  $SYNTAX$
 *      CURDIR( [<cDrive>] )  --> cPath
 *  $ARGUMENTS$
 *      <cDrive> OS drive letter
 *  $RETURNS$
 *      <cPath> Name of directory
 *  $DESCRIPTION$
 *      This function yields the name of the current OS directory on a
 *      specified drive. If <cDrive> is not speficied, the currently logged
 *      drive will be used.

 *      This function should not return the leading and trailing
 *      (back)slashes.

 *      If an error has been detected by the function, or the current OS
 *      directory is the root, the value of the function will be a NULL
 *      byte.
 *  $EXAMPLES$
 *      ? Curdir()
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      FILE()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Command
 *  $NAME$
 *      COPY FILE
 *  $CATEGORY$
 *      Command
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Copies a file.
 *  $SYNTAX$
 *      COPY FILE <cfile> TO <cfile1>
 *  $ARGUMENTS$
 *      <cFile>   Filename of source file
 *      <cFile1>  Filename of target file
 *  $DESCRIPTION$
 *      This command makes an exact copy of <cFile> and names it <cFile1>.
 *      Both files must have the file extension included; the drive and the
 *      directory names must also be specified if they are different from
 *      the default drive and/or director. <cFile1> also can refer to a OS
 *      device (e.g. LPT1). This command does not obsert the SET PATH TO or
 *      SET DEFAULT TO settings.
 *  $EXAMPLES$
 *      COPY FILE C:\harbour\tests\adirtest.prg TO C:\temp\adirtest.prg
 *      COPY FILE C:\harbour\utils\hbdoc\gennf.prg TO LPT1
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $SEEALSO$
 *      ERASE,RENAME,FRENAME(),FERASE()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      HB_FEOF()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Check for end-of-file.
 *  $SYNTAX$
 *      HB_FEOF( <nHandle> ) --> lIsEof
 *  $ARGUMENTS$
 *      <nHandle> The handle of an open file.
 *  $RETURNS$
 *      <lIsEof> .T. if the file handle is at end-of-file, otherwise .F.
 *  $DESCRIPTION$
 *      This function checks an open file handle to see if it is at EOF.

 *      If the file handle is missing, not numeric, or not open, then this
 *      function returns .T. and sets the value returned by FERROR() to -1
 *      (FS_ERROR) or a C-compiler dependent errno value (EBADF or EINVAL).
 *  $EXAMPLES$
 *      nH := FOPEN( "file.txt" )
 *      ? FREADSTR( nH, 80 )
 *      IF HB_FEOF( nH )
 *         ? "End-of-file reached."
 *      ELSE
 *         ? FREADSTR( nH, 80 )
 *      ENDIF
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      H
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      FERROR()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      DIRREMOVE()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Attempt to remove an directory
 *  $SYNTAX$
 *      DIRREMOVE( <cDirectory> ) --> nError
 *  $ARGUMENTS$
 *      <cDirectory>  The name of the directory you want to remove.
 *  $RETURNS$
 *      <nError> 0 if directory was successfully removed, otherwise
 *      the number of the last error.
 *  $DESCRIPTION$
 *      This function attempt to remove the specified directory in <cDirectory>
 *      If this function fail, the it will return the last OS error code number.
 *      See FERROR() function for the description of the error.
 *  $EXAMPLES$
 *      cDir:= ".\backup"
 *      if DIRREMOVE( cDir ) == 0
 *          ? "Remove of directory", cDir, "was successfull"
 *      endif
 *  $TESTS$
 *      See examples
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is CA-Cl*pper 5.3 compliant
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      MAKEDIR(), DIRCHANGE(), ISDISK(), DISKCHANGE(), DISKNAME(), FERROR()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      DIRCHANGE()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Changes the directory
 *  $SYNTAX$
 *      DIRCHANGE( <cDirectory> ) --> nError
 *  $ARGUMENTS$
 *      <cDirectory>  The name of the directory you want do change into.
 *  $RETURNS$
 *      <nError> 0 if directory was successfully changed, otherwise
 *      the number of the last error.
 *  $DESCRIPTION$
 *      This function attempt to change the current directory to the one
 *      specidied in <cDirectory>. If this function fail, the it will return
 *      the last OS error code number. See FERROR() function for the
 *      description of the error.
 *  $EXAMPLES$
 *      if DIRCHANGE( "\temp" ) == 0
 *          ? "Change to diretory was successfull"
 *      endif
 *  $TESTS$
 *      See examples
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is CA-Cl*pper 5.3 compliant
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      MAKEDIR(), DIRREMOVE(), ISDISK(), DISKCHANGE(), DISKNAME(), FERROR()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      MAKEDIR()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Create a new directory
 *  $SYNTAX$
 *      MAKEDIR( <cDirectory> ) --> nError
 *  $ARGUMENTS$
 *      <cDirectory>  The name of the directory you want to create.
 *  $RETURNS$
 *      <nError> 0 if directory was successfully created, otherwise
 *      the number of the last error.
 *  $DESCRIPTION$
 *      This function attempt to create a new directory with the name contained
 *      in <cDirectory>. If this function fail, the it will return the last OS
 *      error code number. See FERROR() function for the description of the
 *      error
 *  $EXAMPLES$
 *      cDir := "temp"
 *      If MAKEDIR( cDir ) == 0
 *          ? "Directory ", cDir, " successfully created
 *      Endif
 *  $TESTS$
 *      See examples
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is CA-Cl*pper 5.3 compliant
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      DIRCHANGE(), DIRREMOVE(), ISDISK(), DISKCHANGE(), DISKNAME(), FERROR()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      ISDISK()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      FileSys
 *  $ONELINER$
 *      Verify if a drive is ready
 *  $SYNTAX$
 *      ISDISK( <cDrive> ) --> lSuccess
 *  $ARGUMENTS$
 *      <cDrive>  An valid Drive letter
 *  $RETURNS$
 *      <lSuccess>  .T. is the drive is ready, otherwise .F.
 *  $DESCRIPTION$
 *      This function attempts to access a drive. If the access to the drive
 *      was successfull, it will return true (.T.), otherwise false(.F.). This
 *      function is usefull for backup function, so you can determine if the
 *      drive that will recieve the backup data is ready or not.
 *  $EXAMPLES$
 *      IF ISDISK( "A" )
 *          ? "Drive is ready "
 *      Endif
 *  $TESTS$
 *      See Examples
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is CA-Cl*pper 5.3 compliant
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      DIRCHANGE(), MAKEDIR(), DIRREMOVE(), DISKCHANGE(), DISKNAME()
 *  $END$
 */