Update SECURITY.md

[MS-DOS.git] / v2.0 / source / UTILITY.txt

                          MS-DOS 2.0

                      Utility Extensions
\f







        The following notation is used below:

        [item]      item is optional.
        item*       item is repeated 0 or more times.
        item+       item is repeated 1 or more times.
        {item1 | item2}
                    item1 is present or item 2 is present  but
                    not both.
        <object>    indicates a syntactic variable.
\f

COMMAND invokation

COMMAND [[<drive>:]<path>] [<cttydev>] [-D] [-P] [-C <string>]

        -P  If  present  COMMAND  will be permanent, otherwise
            this is a transient command.

        -D  If present COMMAND  will  not prompt  for DATE and
            TIME when it comes up.

        d:  Specifies  device  where  command  will  look  for
            COMMAND.COM current default drive if absent.

        <Path>  Specifies  a  directory  on  device  d:   root
            directory if absent.

        <cttydev> Name of the CTTY device.  /DEV/CON if absent
            and  command  is permanent.  The /DEV/ may be left
            off if AVAILDEV is TRUE (see sysinit doc).

        -C <string> If present -C must  be  the  last  switch.
            This  causes  COMMAND to try to execute the string
            as if the user had typed it at the standard input.
            COMMAND  executes  this  single command string and
            then exits.  If the -P switch  is  present  it  is
            ignored  (can't  have  a single command, permanent
            COMMAND).  NOTE: ALL of the text  on  the  command
            line  after  the  -C is just passed on.  It is not
            processed for more arguments, this is why -C  must
            be last.

COMMAND extensions

IF <condition> <command>

    where <condition> is one of the following:

        ERRORLEVEL <number>
            true if and only if the previous program EXECed by
            COMMAND had an exit code of <number> or higher.

        <string1> == <string2>
            true if and only if <string1>  and  <string2>  are
            identical  after  parameter substitution.  Strings
            may not have embedded delimiters.

        EXIST <filename>
            true if and only if <filename> exists.

        NOT <condition>
            true if and only if <condition> is false.

    The IF statement allows conditional execution of commands.
    When  the  <condition>  is  true,  then  the  <command> is
    executed otherwise, the <command> is skipped.

    Examples:

    IF not exist /tmp/foo ECHO Can't find file /tmp/foo

    IF $1x == x ECHO Need at least one parameter

    IF NOT ERRORLEVEL 3 LINK $1,,;


FOR %%<c> IN <set> DO <command>

    <c> can be  any character but 0,1,2,3,..,9 (so there is no
        confusion with the %0 - %9 batch parameters).

    <set> is ( <item>* )

    The %%<c> variable is sequentially set to each  member  of
    <set>  and  then  <command>  is evaluated.  If a member of
    <set> is an expression involving  *  and/or  ?,  then  the
    variable  is  set  to each matching pattern from disk.  In
    this case only one such <item> may  be  in  the  set,  any
    <item>s after the first are ignored.

    Example:

    FOR %%f IN ( *.ASM ) DO MASM %%f;

    for %%f in (FOO BAR BLECH) do REM %%f to you

    NOTE:   The  '%%'  is needed so that after Batch parameter
        (%0 - %9) processing is done, there is one  '%'  left.
        If only '%f' were there, the batch parameter processor
        would see the '%' then look at 'f', decide  that  '%f'
        was  an  error (bad parameter reference) and throw out
        the '%f' so that FOR would never see it.  If  the  FOR
        is  NOT  in  a batch file, then only ONE '%' should be
        used.
\f

SHIFT

    Currently,  command  files  are  limited  to  handling  10
    parameters:  %0 through %9.  To allow access to more  than
    these,  the  command  SHIFT  will  perform  a 'pop' of the
    command line parameters:

        if  %0 = "foo"
            %1 = "bar"
            %2 = "blech"
            %3...%9  are empty

        then a SHIFT will result in the following:

            %0 = "bar"
            %1 = "blech"
            %2...%9 are empty

    If  there  are  more than 10 parameters given on a command
    line, then the those that appear after the 10th (%9)  will
    be shifted one at a time into %9 by successive shifts.

:<label>

    This  is  essentially  a no-op.  It defines a label in the
    batch file for a subsequent GOTO.  It may also be used  to
    put  comment  lines  in  batch  files since all lines that
    start with ':'  are ignored.

GOTO <label>

    Causes commands to be taken from the batch file  beginning
    with  the  line after the <label> definition.  If no label
    has been defined, the current batch file will terminate.

    Example:

    :foo
    REM looping...
    GOTO foo

    will  produce  a  infinite  sequence  of  messages:
    'REM looping...'

    NOTE: Labels are case insensitive, :FOO == :foo == :Foo
\f

ECHO [{ON | OFF | <message>}]

    Normally, commands in a BATCH file  are  echoed  onto  the
    standard  output  as  they  are seen by COMMAND.  ECHO OFF
    turns off this feature.  ECHO ON turns  echoing  back  on.
    If ON  or OFF is not specified and there is text following
    the command, that text (a message) is echoed  to  standard
    output.   If  there  are  no arguments at all, the current
    setting of echo (on or off)  is  echoed  to  the  standard
    output in the form:

        ECHO is xxx

    Where xxx is "on" or "off".

Redirection of standard input/standard output.

    Programs  that  read  from  the  keyboard and write to the
    screen are said to be doing I/O to the standard input  and
    standard  output.   Using any of the following will result
    in I/O to these standard devices:

        Writing to default  handles  1  /  read  from  default
        handle 0.

        Doing byte I/O using system calls 1, 2, 6-12.

    These standard  devices may be redirected to/from files by
    the following in command line arguments:

        > <filename>
            causes  <filename>  to be created (or truncated to
            zero length) and then assigns standard  output  to
            that  file.   All  output from the command will be
            placed in the file.

        < <filename>
            causes   standard   input   to   be   assigned  to
            <filename>.  All input to the  command  will  come
            from  this  file.  If end-of-file is reached, then
            system calls 1, 2, 6-12 will  return  ^Z  ,  while
            reading from handle 0 will return zero characters.

        >> <filename>
            causes  <filename>  to  be  opened   (created   if
            necessary) and  positions the write pointer at the
            end of  the  file  so  that  all  output  will  be
            appended to the file.

    Note  that  the  above will not appear in the command line
    that the program being invoked sees.

    Examples:

    DIR *.ASM > FOO.LST
        Sends  the  output  of  the  dir  command  to the file
        FOO.LST.
\f

    FOR %0 IN (*.ASM) DO MASM %0; >>ERRS.LST
        Sends all error output from assembling every .ASM file
        into the file ERRS.LST.

Piping of standard I/O

    It  is  often  useful  for the output of one program to be
    sent as input to another program.  A  typical  case  is  a
    program  that  produces columnar output that must later be
    sorted.

    The pipe feature allows this to  occur  naturally  is  the
    programs do all of their I/O to the standard devices.

    For  example,  if  we  had a program SORT that read all of
    it's standard input, sorted it and then wrote  it  to  the
    standard  output,  then  we  could  get a sorted directory
    listing as follows:

    DIR | SORT

    The | would cause all standard  output  generated  by  the
    left-hand command  to be sent to the standard input of the
    right-hand command.

    If we wanted the sorted directory to be sent to a file, we
    type:

    DIR | SORT >FILE

    and away it goes.

    The piping  feature is implemented as sequential execution
    of the procedures with redirection to and  from  temporary
    files.   In  the  example above, the following would be an
    exact equivalent:

    DIR >/tmp/std1
    SORT </tmp/std1 >FILE

\f

        The  pipe  is  not a real pipe but rather a quasi-pipe
    that uses temporary files to hold the input and output  as
    it sequentially  executes the elements of the pipe.  These
    files are created in the current directory, of the current
    drive and  have the form %PIPEx%.$$$, where x will be 1 or
    2.  This means that any program that runs in the pipe must
    be  sure  to restore the current directory and drive if it
    has changed them, otherwise the pipe files will be lost.


VER
    Prints DOS version number.

VOL [<drive>:]
    Prints the volume ID of the disk in drive d:.  No d:  does
    default drive.

CHDIR [{<drive>: | <path>}]
    Change  directory,  or  print  current.   directory.If  no
    argument is given, the current directory  on  the  default
    drive  is  printed.   If  d:   alone is given, the durrent
    directory of drive d is printed.   Otherwise  the  current
    directory is set to path.

    NOTE:"CD" is accepted as an abbreviation.

MKDIR <path> - Make a directory.
    "MD" is accepted as an abbreviation.

RMDIR <path> - Remove a directory.
    "RD" is accepted as an abbreviation.
     The directory must be empty except for
      '.' and '..'.

    <path>  -  A  standard  XENIX style path with the optional
        addition of a drive spec:

            A:/FOO/BAR      Full path
            /FOO/BAR        Full path, current drive
            FOO/BAR         Current dir relative
            A:FOO/BAR          "     "     "

VERIFY [{ON | OFF}]
    Select/deselect verify after write mode.  This  supliments
    the  V  switch  to  the  COPY command.  Once turned ON, it
    stays on until some program changes it (via the set verify
    system  call)  or  the VERIFY OFF command is given.  If no
    argument is  given,  the  current  setting  of  VERIFY  is
    printed to the standard output in the form:

        VERIFY is xxx

    Where xxx is "on" or "off".

PATH [<path>{;<path>}*]
    Set command  search  paths.   This  allows  users  to  set
    directories that  should be searched for external commands
    after a search of the  current  directory  is  made.   The
    default value  is /bin.  In addition there are two special
    cases:  PATH all by itself with no  arguments  will  print
    the current  path.  Path with the single argument ';' (ie.
    "PATH ;") will set the NUL path (no directories other than
    the  current  one searched).  If no argument is given, the
    current value of PATH is printed to the standard output in
    the form:

        PATH=text of path
          or
        No path

    NOTE:   On  IBM  systems,  the default value of path is No
        path.

EXIT
    For COMMANDs run without the P switch, this causes COMMAND
    to return.  For a normal COMMAND it  causes  a  return  to
    itself.

BREAK [{ON | OFF}]
    Like in CONFIG.SYS, "BREAK ON"  turns  on  the  Control  C
    check  in  the DOS function dispatcher.  "BREAK OFF" turns
    it off.  If no argument is given the setting of  BREAK  is
    printed to the standard output in the form:

        BREAK is xxx

    Where xxx is "on" or "off".

PROMPT [<prompt-text>]
    Set the  system  prompt.   MS-DOS  prompts  are  now  user
    settable, all  of the text on the command line is taken to
    be the new prompt.  If no text is present  the  prompt  is
    set  to  the  default  prompt.  There are meta strings for
    various special prompts.  These are of the form '$c' where
    c is one of the following:

        $ - The '$' character.
        t - The time.
        d - The date.
        p - The current directory of the default drive.
        v - The version number.
        n - The default drive.
        g - The '>' character.
        l - The '<' character.
        b - The '|' character.
        s - The ' ' character.
        e - The ESC character.
        _ - A CR LF sequence.

    EXAMPLE:
        PROMPT $n:
                Would set the normal MS-DOS prompt.
        PROMPT $n>
                Would det the normal PC-DOS prompt.
        PROMPT Time = $t$_Date = $d
                Would set a two line prompt which printed
                Time = (current time)
                Date = (current date)

    NOTE:  For '$c' sequences, lower case =  upper  case,  and
        any  character  not  on  the  above  list is mapped to
        nothing.

SET (ENVNAME)=(ENVTEXT)
    Set environment  strings.  This command inserts strings in
    COMMAND's environment.  For instance:

    SET PROMPT=$n>
        Duplicates the function of the PROMPT command.
    SET PATH=p1;p2
        Duplicates the function of the PATH command.
    SET foo=bar
        Puts the string FOO=bar into the environment (note the
        case mapping of (ENVNAME)).

    NOTE:  Environments are very flexible, almost anything can
        be put  into the environment with the SET command; the
        only requirement is that a single '='  be  present  in
        the string.

CLS
    Clear screen, causes the ANSI escape sequence ESC[2J to be
    sent to standard output.

CTTY /DEV/dev - Change console TTY. For instance:

                CTTY /DEV/AUX

                Would move all command I/O to the AUX port.

                CTTY /DEV/CON

                Would move  it back to the normal device.  The
                /dev/ prefix may be left off  if  AVAILDEV  is
                TRUE (see configuration-file doc).

COMMAND internal commands take path arguments.

        DIR <path>

        COPY <path> <path>

        DEL(ERASE) <path>
                If the path is a dir, all files  in  that  dir
                are deleted.
        NOTE: The "Are you sure  (Y/N)"  prompt  for  DEL  and
                ERASE  now  uses  buffered  standard input, so
                users must type a return after  their  answer.
                This gives  them the chance to correct if they
                type 'y' by mistake.

        TYPE <path>   (must specify a file)

\f


FILCOM - compare two files

    The  FILCOM  program compares two files and produces a log
    of differences between them.  The comparison may  be  made
    in  two  fashions; either on a line-by-line basis, or on a
    byte-by-byte basis.

    The line-by-line compare will isolate blocks of lines that
    are  different  between  the  two files and will print the
    blocks from each file.  The line-by-line  compare  is  the
    default  when  neither of the two files being compared has
    the extension .EXE, .COM, or .OBJ.

    The byte-by-byte compare will display exactly which  bytes
    are different between the two files.  If either file being
    compared has extension .EXE, .COM, or .OBJ then the  files
    will be compared in byte-by-byte mode.
\f


RECOVER - recover files from a trashed disk.

    If a sector on a disk goes bad, you can recover either the
    file that contained that sector (without  the  sector)  or
    the entire  disk (if the bad sector was in the directory).

    To recover a particular file:

    RECOVER <file-to-recover>

    This  will  cause the file to be read sector by sector and
    to be have the bad sector skipped.  Note that this implies
    that the allocation unit containing the bad sector will be
    read as much as possible.   When  such  a  bad  sector  is
    found,  its  containing  allocation unit is marked as bad,
    thus preventing future allocations of that bad sector.

    To recover a particular disk:

    RECOVER <drive-letter>:

    This will cause a scan to be made of the drive's  FAT  for
    chains of  allocation units (files).  A new root directory
    is then written that has entries  of  the  form  FILEnnnn.
    Each  FILEnnnn  will  point  to  the  head  of  one of the
    allocation unit chains.

    If there are more chains than  directory  entries  in  the
    root, RECOVER prints a message and leaves the un-RECOVERED
    chains in the FAT so that RECOVER can be  run  again  once
    some room has been made in the ROOT.
\f


DEBUG ON MS-DOS 2.0


    When 2.0 DEBUG is invoked it  sets  up  a  program  header
atoffset 0  in its program work area.  On previous versions it
was OK to overwrite this header with impunity:  this  is  true
of  the  default  header  set  up if no <filespec> is given to
DEBUG.  If DEBUGging a .COM or .EXE file, however, you must be
careful  not  to  tamper  with the header of the program below
address 5CH, to do this will probably result in a  crash.   It
is  also  important that an attempt is not made to "restart" a
program once the  "program  terminated  normally"  message  is
given.  The program must be reloaded with the N and L commands
in order for it to run properly.

NEW FEATURES

The A (Assemble) Command

FORMAT:    A [<address>]

PURPOSE:   To assemble 8086/8087/8088 mnemonics directly into
           memory.

o   If a syntax error is encountered, DEBUG responds with

               ^ Error

    and redisplays the current assembly address.

o   All numeric  values  are  hexadecimal  and  may be entered
    as 1-4 characters.

o   Prefix mnemonics must be entered in front  of  the  opcode
    to  which  they  refer.   They  may  also  be entered on a
    separate line.

o   The segment override mnemonics  are  CS:,  DS:,  ES:,  and
    SS:

o   String manipulation  mnemonics  must  explictly  state the
    string size.  For example,  the  MOVSW  must  be  used  to
    move word  strings  and  MOVSB  must  be used to move byte
    strings.


o   The mnemonic for the far return is RETF.

o   The assembler  will  automatically  assemble  short,  near
    or far jumps and  calls  depending  on  byte  displacement
    to the  destination  address.   These  may  be  overridden
    with the NEAR or FAR prefix.  For example:

    0100:0500 JMP   502             ; a 2 byte short jump
    0100:0502 JMP   NEAR 505        ; a 3 byte near jump
    0100:0505 JMP   FAR 50A         ; a 5 byte far jump

    The NEAR prefix may be  abbreviated  to  NE  but  the  FAR
    prefix cannot be abbreviated.

o   DEBUG cannot  tell  whether  some operands refer to a word
    memory location or a byte memroy location.  In  this  case
    the data  type  must  be  explicity stated with the prefix
    "WORD PTR" or "BYTE PTR".   DEBUG  will  also  except  the
    abbreviations "WO" and "BY".  For example:

        NEG     BYTE PTR [128]
        DEC     WO [SI]

o   DEBUG also cannot tell whether  an  operand  refers  to  a
    memory location  or  to  an immediate operand.  DEBUG uses
    the common convention that  operands  enclosed  in  square
    brackets refer to memory.  For example:

        MOV     AX,21           ;Load AX with 21H
        MOV     AX,[21]         ;Load AX with the contents
                                ;of memory location 21H

o   Two popular  pseudo-instructions  have also been included.
    The DB opcode will  assemble  byte  values  directly  into
    memory.  The  DW opcode will assemble word values directly
    into memory.  For example:

        DB      1,2,3,4,"THIS IS AN EXAMPLE"
        DB      'THIS IS A QUOTE: "'
        DB      "THIS IS A QUOTE: '"

        DW      1000,2000,3000,"BACH"


o   All forms of the register indirect commands are supported.
    For example:

        ADD     BX,34[BP+2].[SI-1]
        POP     [BP+DI]
        PUSH    [SI]

o   All opcode synonyms are supported, For example:

         LOOPZ  100
         LOOPE  100

         JA     200
         JNBE   200

o   For  8087  opcodes  the  WAIT  or  FWAIT  prefix  must  be
    explictly specified.  For example:

        FWAIT FADD ST,ST(3)     ; This lines  will  assemble
                                ; a FWAIT prefix

        FLD TBYTE PTR [BX]      ; This line will not
\f


FORMAT enhancements

    FORMAT  will  now  install  volume  id's during the format
    process.  DIR and CHKDSK will display these volume id's.

    User programs can read the volume id on a particular drive
    by doing a 'search next' with the volume id attribute.  It
    is impossible, using normal DOS calls, to delete a  volume
    id  or  to  create  another one.  The only way to create a
    volume id is to reformat the disk.

    NOTE: On IBM systems the V switch must be given to  FORMAT
    to have it do Volume IDs.

\f


CHKDSK FOR MS-DOS 2.0


    MS-DOS  2.0  has  a tree structured directory scheme which
did not exist on previous versions of  MS-DOS.   As  a  result
CHKDSK  is  a  much  more  complex  program  than  in previous
versions since it must perform a tree traversal to find all of
the  files  on  a  given  disk.   It  employes  a  depth first
traversal in order to accomplish this.

    Previous  versions   of   CHKDSK   automatically   "fixed"
disks (regardless of whether it was appropriate).  CHKDSK 2.00
run normally will not alter the disk in  any  way,  it  simply
reports  on  any  inconsistencies  found.  To actually "fix" a
disk CHKDSK must be run with the F switch (Fix).  This  allows
you to  perhaps take some alternate (to CHKDSK repairs) action
before letting CHKDSK loose on your disk.

    CHKDSK 2.00 will report on non-contiguous allocation units
(extents)  for  specified files.  This is handy for gaging how
"fragmented" a disk volume has become.  This is done by simply
giving a filespec:

        CHKDSK B:*.*

This  would  report  extents  for  all  files  in  the current
directory for drive B after doing a normal  consistency  check
on  drive  B.  Files which have many extents can be copied and
renamed to restore them to a contiguous state, thus  improving
I/O performance to the files.

    Previous    versions   of   CHKDSK   would   simply   free
allocation units which were  marked  as  used,  but  were  not
actually  part  of  any  file.  CHKDSK 2.00 will recover these
"orphan" allocation units if specified.  If orphan  allocation
units  are  found,  CHKDSK  prompts for free or recover.  Free
just frees the orphans as previous versions did, recover  will
employ  allocation  chain analysis to create "orphan files" in
the root directory of the disk.  These  files  will  have  the
form  "%ORPHAN%.l$$"  where  l  will  take on some ASCII value
greater than '@'.  These files may then be inspected to see if
valuable  data  was contained in them.  If there is not enough
room to make all of the  "orphan"  files,  CHKDSK  leaves  the
unrecovered chains  in the FAT so that CHKDSK can be run again
(once some entries in the  ROOT  have  been  deleted).   NOTE:
Making ORPHAN files is a SLOW process.

    Verbose  mode.   CHKDSK  2.00 may be run with the V switch
which causes a  trace  of  the  files  and  directories  being
processed to be printed as CHKDSK runs.

\f
FILTERS FOR MS-DOS 2.0

    A filter is a utility  that  reads  from  standard  input,
modifies  the  information in some way, then writes the result
to standard output.  In this way the data is said to have been
"filtered"  by  the  program.   Since different filters can be
piped together in many different ways a few filters  can  take
the place of a large number of specific purpose programs.  The
following describes the filters that are provided with  MS-DOS
2.0:

CIPHER <key word>

    Cipher  reads  a  program from standard input, encrypts it
using the key word provided  by  the  user,  then  writes  the
result  to  standard  output.   To decrypt the file simply run
CIPHER again using the same keyword.  For example:

A>CIPHER MYSTERY <NSA.CIA  >SECRET.FIL

    This command line will read file NSA.CIA, encrypt it using
the  key  word  "MYSTERY",  then  write  the  result  to  file
SECRET.FIL To view the original  file  the  following  command
line could be used:

A>CIPHER MYSTERY <SECRET.FIL

    This will read file SECRET.FIL, decrypt the file using the
key word "MYSTERY", then write the result to standard  output,
which in this case is the console.

FGREP

    This  filter  takes as arguments a string and optionally a
series of file names.  It will send  to  standard  output  all
lines  from  the  files  specified  in  the  command line that
contain the string.

    If no files are specified FGREP will take the  input  from
standard  in.   The  format for the command line invocation of
FGREP is:

FGREP [<option>] <string> <filename>*

     The options available are:

        /v      Will cause  FGREP  to  output  all  lines  NOT
                containing the specified string.

        /c      Will  cause  FGREP  to only print the count of
                lines matched in each of the files.

        /n      Each line matched is preceded by its  relative
                line number in the file.

    The  string  argument should be enclosed in double quotes.
Two double quotes in succession are taken as a  single  double
quote.  So,

A>FGREP "Fool""s Paradise" book1.txt book2.txt bible

will output  all lines from the book1.txt, book2.txt and bible
(in that order that contain the  string:   Fool"s  Paradise  .
And,

A>dir b: | fgrep /v "DAT"

will  output  all  names of the files in disk b:  which do not
contain the string DAT .

MORE

    The filter MORE  reads  from  standard  input,  sends  one
screen full  of information to standard output and then pauses
with message:

-- More --

    Pressing the RETURN key will cause another screen full  of
information  to  be  written to standard output.  This process
continues until all the input data is read.

SORT [/R] [/+n]

    Sort reads from standard input, sorts the data, the writes
the  information  to  standard output.  The sort is done using
the ASCII collating sequence.  There are switches which  allow
the user to select various options:

   R - Reverse the sort, that is make "Z" come before "A"

  +n - Sort starting  with column "n" where n is some integer.
       The default is start the  comparisons  with  column  1,
       this switch allows the user to start in any column.

example:

A>SORT /R <UNSORT.TXT >SORT.TXT

This command  line will read the file UNSORT.TXT, do a reverse
sort, then write the output to file SORT.TXT

A>DIR | SORT /+14

    This command line will cause the output of  the  directory
command  to  be piped to the sort filter, the sort filter will
sort starting with column 14 (This is the column the file size
starts),  then  send  the  output  to  the  console.   Thus  a
directory sorted by file size will be the result.  To get real
fancy:

A>DIR | SORT /+14 | MORE

will do the same thing except that MORE will give you a chance
to read the directory before it scrolls off the screen.