

                              THE PROGRAM  

This file ATTRIB.TXT covers ATTRIB.COM v1.09a, dated 04-24-2000, by Charles
Dye.  At present, I can be reached as raster@highfiber.com.

This program and documentation file are Copyright 1997-2000, Charles Dye.
They are freeware distributed under the GNU General Public License.  Please
read the section "Distribution", below, for information.


                             THE BASIC IDEA  

This is a freeware clone of the ATTRIB.EXE utility which ships with MS-DOS
and PC DOS.  Since ATTRIB.EXE (which I'll refer to as "Microsoft's" although
it might be IBM's) is a well-known and well-documented utility, I'll gloss
over ATTRIB's basic operation and spend most of my time on the differences
between my ATTRIB and Microsoft's.

Use ATTRIB to display and to change attributes for files.  Under MS-DOS and
compatible operating systems, there are four basic attributes which files may
have.  These attributes are all single bits:  they can either be "set" (on)
or "cleared" (off.)  The four attributes are identified by letters.

The A attribute (for "Archive needed") indicates that a file has been created
or changed since the last backup.  The H ("Hidden") and S ("System") bits
prevent files from appearing in normal directory listings.  The R attribute
("Read-only") protects files from being changed or deleted.


                             PROGRAM SYNTAX  

ATTRIB [operators] [filespecs] [switches]

Arguments may appear in any order.  Separate them with spaces.  Case is not
significant.

Filespecs may include wildcards, may be DR DOS-style file lists, or may name
subdirectories.  You may put quote marks around filenames to "trap" spaces or
other troublesome characters.  You may uses slashes within a filename as path
separators, but do not begin a filename with a slash.  If you do not specify
any filespecs, ATTRIB will use *.* by default.

Legal operators are:

+    Set the following attributes.  +AH would set the "Archive needed" and
     the "Hidden" bits.  Legal attribute letters are A, S, H, R, and Z.

-    Clear the following attributes.  -SHR would clear the "System," "Hidden"
     and "Read-only" bits.

~    Toggle (invert) the following attributes.  ~A would set the A bit if it
     was cleared, and clear it if it was set.

=    Exact:  set only the following attributes, and clear all others.  =AH
     would set the A and H bits, and clear the S and R bits.

,    Clear all attributes; equivalent to -ASHR.  Don't type any letters after
     the comma, and don't combine it with the other operators or /C.

Legal switches are:

/S   Process files in subdirectories.  /R is a synonym.

/P   Prompt the user before changing each file.  /Q is a synonym.

/B   Displays information in a batch-file-compatible format.

/V   Displays information in a verbose style (the default.)  Use this switch
     to override any previous /N or /B.

/N   Displays information in the traditional, Microsoft-style format.

/M   More.  Pause after each screenful of information.  Use /M:x to pause
     after every x lines.

/D   Allows filespecs with wildcards to match subdirectory names.  By default
     my ATTRIB behaves like Microsoft's:  it will not match subdirectories if
     you use wildcards.

/C=filename
     Copies attributes from another file.  The filename may include a drive
     letter or pathname.  If the filename contains wildcards, the first
     matching file (not subdirectory!) will be used.  If the filename does
     not contain wildcards, it may name a subdirectory instead of a file.

/A:mask
     Filter by attributes.  ATTRIB /A:A-S would display or change only items
     with the Archive bit set and the System bit clear.

/F   Sets the format for date display.  /F:U uses the United States format of
     month/day/year.  /F:E uses the European format of day/month/year.  /F:J
     or /F:I uses the Japanese and ISO standard of year/month/day.  If there
     is no /F switch, ATTRIB will use the default local format.

/H   Do not hook the INT 24 critical-error vector.


                       DIFFERENCES FROM MICROSOFT'S  

Of course, I wouldn't have re-implemented such a common and basic utility if
I didn't think some improvements could be made ....

My ATTRIB is much more verbose.  It displays information on the attributes,
dates, times, and sizes of the files it finds.  This can make it easier to
guess what a file might contain:  is it eight years old?  Four megs long?
Was it created after 10 p.m. on a Saturday?  Microsoft's utility only shows
filenames, and usually not even those.

My ATTRIB allows you to change any attribute without reference to any of the
others.  Microsoft's may give a "Not resetting system file thus-and-so" error
message, forcing you to retype your command line -- an obnoxious feature.

Microsoft's ATTRIB does surprisingly little error checking.  If DOS does not
report an error, it assumes that attributes were set correctly.  Mine checks
the file to make sure that the attributes were set as expected, and flags an
error if they weren't.

My ATTRIB includes support for a Z pseudo-attribute, which I define as the
logical-OR of the S, H, and R bits.  Setting Z will actually set S, H, and R.
Clearing Z will clear all three.  Toggling Z will set S, H, and R if all
three were clear, and clear them if any were set.  Changes to the Z bit do
not affect the Archive attribute.  I use this virtual attribute as a shortcut
to quickly change system boot files into normal files, and vice versa.

The toggle operator (tilde):  A common operation in DOS is to clear some
attributes on a file, do something with the file, and then set the same
attributes back.  Using a command-line history utility like DOSKEY and my
ATTRIB's toggle operator simplifies the process:  ATTRIB ~Z MSDOS.SYS then
EDIT MSDOS.SYS then another ATTRIB ~Z MSDOS.SYS.  Since the first and last
commands are identical, you don't have to edit the original command line.

Environment variables:  You can add default switches to an environment
variable.  If there is a variable named CDATTRIB, it will be processed before
the command line.  If there is no CDATTRIB, the program will check for a
variable named ATTRIB instead.  Most switches are legal in the environment
variable, but /C and /A will be ignored.  Filespecs and operators (+ - ~ ,)
will also be ignored.

Other added features:  DR DOS-style file lists (prefix them with an @-sign.)
Prompting (/P) and paging (/M) and attribute copying (/C).  Multiple
filenames on the same command line.  Multiple attributes after an operator.
Not DOS-version specific; mine will work with any DOS from 3.0 on up.

The filename.  Since the MS-DOS utility is usually named ATTRIB.EXE, you can
copy my ATTRIB.COM into your DOS directory.  It will override the Microsoft
utility without replacing it, because the command shell searches for .COM
programs before .EXEs.  Cool, huh?

My ATTRIB is significantly smaller than Microsoft's, which is always nice.


                               FILE LISTS  

The filespec may name a DR DOS-style file list.  ATTRIB +H @LISTFILE will
open the file named LISTFILE and read filespecs from it.  LISTFILE should be
a text file containing valid DOS filespecs, one per line.  You can create a
file list using any text editor.  You can also use DIR /B, redirecting its
output into a file list; or you can create a file list by using a file-finder
such as LOCATE.

Filespecs read from a file list are treated almost exactly like filespecs
typed on the command line.  They may be enclosed in quote marks, may contain
wildcards, may name drives or directories, and so forth.  However, a filename
beginning with an @-sign is not treated as another file list.  File lists may
not be nested.

A file list may also contain comment lines beginning with a semicolon or
colon.  Lines beginning with a semicolon are "remarks" and will be ignored.
Lines beginning with a colon are "notices" which ATTRIB will print to the
screen.  Remarks and notices are not standard file-list syntax, but
extensions which I have added.  Don't use either one if you want your file
list to be compatible with the DR DOS utilities.

Examples of using double quotes with file list names:  ATTRIB +R "@OUTPUT"
will set a file named "@OUTPUT" (with the leading at-sign) to Read-only.
ATTRIB +R @"OUTPUT" will instead open the file named OUTPUT and read
filenames from it, setting each file named to Read-only.  ATTRIB @"FOO BAR"
would open the file named "FOO BAR" (with an embedded space), and use it as a
file list.

WARNING:  If you use /S along with a file list, the /S will also apply to
filenames read in from the list!  If you have a file list named FOO which
has only one line D:\ then the command ATTRIB +H @FOO /S will merrily hide
*all* files on drive D:  This is a powerful, but dangerous and non-obvious,
feature.  In general, don't combine /S and file lists unless you're certain
that you want to recurse into an uncertain set of subdirectories....


                             SUNDRY CREDITS  

This program is created with NASM, the Netwide Assembler, a freely available
80x86 assembler.  NASM's home page is:  http://www.web-sites.co.uk/nasm/

I compress the executable using UPX.  The UPX home page is:
http://upx.tsx.org/

The code was originally written for Eric Isaacson's shareware assembler A86.


                              WHAT'S NEW?  

Version 1.09b  01-01-2001   5,107 bytes                       AC33CAF7  36B9

Trivial change:  /C now permits a comma instead of the equals sign, to allow
for changes to filename completion in the latest 4DOS.

Version 1.09a  04-24-2000   5,109 bytes                       D05C47F4  C2E9

Filespec buffers increased to 260 bytes to handle the super-long pathnames
permitted by Windows 95/98.

Version 1.09   02-29-2000   5,095 bytes                       00D58034  691F

New = operator sets only the specified bits, and clears all others.  Useful
for copying or restoring attributes using LOCATE's &B display macro, or
the 4DOS @ATTRIB[] function.

Version 1.08   12-30-1999   4,959 bytes                       E312F87E  ED52

Two changes to /N for better compatibility with Microsoft's utility.  First,
if no matching files are found, an error message will be displayed and
errorlevel 1 will be returned.  Second, if any attributes are to be changed,
nothing will be displayed the screen.  These changes only affect /N mode.
Also, the colon after /A is now optional, as with DIR.

Version 1.07   10-04-1999   4,927 bytes                       0F09CCD2  FB6C

Added /A: (mask by attributes).  Added /F:I as a synonym for /F:J (ISO date
format).  Added /? /C? /F? /M? /A? to display syntax help to standard output
(so it can be redirected to a file).  Allow _ and D as do-nothing attributes
after an operator for compatibility with the 4DOS @ATTRIB function.  Allow
operators to be run together without intervening spaces -- e.g. you can now
use +S-H instead of +S -H.  Also, added several %defines to make it easy to
remove undesired functions.  Compressed the executable with UPX.


                              DISTRIBUTION  

This program is copyrighted, but may be freely distributed under the terms of
the Free Software Foundation's GNU General Public License v2 (or later, at
your option.)  See the file COPYING for the legalities.  If you did not
receive a copy of COPYING with this program, you may request one from the
Free Software Foundation, Inc. at:

        59 Temple Place - Suite 330
        Boston, MA  02111-1307, USA.

NO WARRANTY:  Like all things free, you get no warranty for ATTRIB.  I
believe it to work substantially as documented here, and have made reasonable
efforts to test it in a variety of different situations.  However, I cannot
and will not be responsible for any unforseen consequences.  Use At Your Own
Risk.  (You're welcome to send me bug reports, of course.)

