file_tool - display or modify sections of a file
This program can be used to display or edit data in arbitrary
files. If no '-mod_data' option is provided (with DATA), it
is assumed the user wishes only to display the specified data
(using both '-offset' and '-length', or using '-ge_XXX').
usage: file_tool [options] -infiles file1 file2 ...
examples:
----- help examples -----
1. get detailed help:
file_tool -help
2. get descriptions of GE struct elements:
file_tool -help_ge
----- GEMS 4.x and 5.x display examples -----
1. display GE header and extras info for file I.100:
file_tool -ge_all -infiles I.100
2. display GEMS 4.x series and image headers for file I.100:
file_tool -ge4_all -infiles I.100
3. display run numbers for every 100th I-file in this directory
file_tool -ge_uv17 -infiles I.?42
file_tool -ge_run -infiles I.?42
----- general value display examples -----
1. display the 32 characters located 100 bytes into each file:
file_tool -offset 100 -length 32 -infiles file1 file2
2. display the 8 4-byte reals located 100 bytes into each file:
file_tool -disp_real4 -offset 100 -length 32 -infiles file1 file2
3. display 8 2-byte hex integers, 100 bytes into each file:
file_tool -disp_hex2 -offset 100 -length 16 -infiles file1 file2
----- ANALYZE file checking examples -----
1. define the field contents of an ANALYZE header
file_tool -def_ana_hdr
2. display the field contents of an ANALYZE file
file_tool -disp_ana_hdr -infiles dset.hdr
3. display field differences between 2 ANALYZE headers
file_tool -diff_ana_hdrs -infiles dset1.hdr dset2.hdr
4. display field differences between 2 ANALYZE headers (in HEX)
file_tool -diff_ana_hdrs -hex -infiles dset1.hdr dset2.hdr
5. modify some fields of an ANALYZE file
file_tool -mod_ana_hdr -prefix new.hdr -mod_field smin 0 \
-mod_field descrip 'test ANALYZE file' \
-mod_field pixdim '0 2.1 3.1 4 0 0 0 0 0' \
-infiles old.hdr
----- script file checking examples -----
0. check for any script issues (Unix, backslashes, chars)
(-test is the same as -show_bad_all)
file_tool -test -infiles my_scripts_*.txt
1. in each file, check whether it is a UNIX file type
file_tool -show_file_type -infiles my_scripts_*.txt
2. in one file, convert a non-UNIX file type to UNIX
(basically a dos2unix operation)
file_tool -show_file_type -infile non.unix.txt -prefix is.unix.txt
3. in each file, look for spaces after trailing backslashes '\'
file_tool -show_bad_backslash -infiles my_scripts_*.txt
4. in ONE file, correct spaces after trailing backslashes '\'
file_tool -show_bad_backslash -infile scripts.txt -prefix s.fixed.txt
5. add line wrappers (multiple examples):
file_tool -wrap -infile script.txt
file_tool -wrap_method rr -infile script.txt
cat script.txt | file_tool -wrap -infile stdin
----- character modification examples -----
1. in each file, change the 8 characters at 2515 to 'hi there':
file_tool -mod_data "hi there" -offset 2515 -length 8 -infiles I.*
2. in each file, change the 21 characters at 2515 to all 'x's
(and print out extra debug info)
file_tool -debug 1 -mod_data x -mod_type val -offset 2515 \
-length 21 -infiles I.*
----- raw number modification examples -----
1. in each file, change the 3 short integers starting at position
2508 to '2 -419 17'
file_tool -mod_data '2 -419 17' -mod_type sint2 -offset 2508 \
-length 6 -infiles I.*
2. in each file, change the 3 binary floats starting at position
2508 to '-83.4 2 17' (and set the next 8 bytes to zero by
setting the length to 20, instead of just 12).
file_tool -mod_data '-83.4 2 17' -mod_type float4 -offset 2508 \
-length 20 -infiles I.*
3. in each file, change the 3 binary floats starting at position
2508 to '-83.4 2 17', and apply byte swapping
file_tool -mod_data '-83.4 2 17' -mod_type float4 -offset 2508 \
-length 12 -swap_bytes -infiles I.*
notes:
o Use of '-infiles' is required.
o Use of '-length' or a GE information option is required.
o As of this version, only modification with text is supported.
Editing binary data is coming soon to a workstation near you.
special options:
-help : show this help information
: e.g. -help
-version : show version information
: e.g. -version
-hist : show the program's modification history
-debug LEVEL : print extra info along the way
: e.g. -debug 1
: default is 0, max is 2
required 'options':
-infiles f1 f2 ... : specify input files to print from or modify
: e.g. -infiles file1
: e.g. -infiles I.*
Note that '-infiles' should be the final option. This is
to allow the user an arbitrary number of input files.
GE info options:
-ge_all : display GE header and extras info
-ge_header : display GE header info
-ge_extras : display extra GE image info
-ge_uv17 : display the value of uv17 (the run #)
-ge_run : (same as -ge_uv17)
-ge_off : display file offsets for various fields
GEMS 4.x info options:
-ge4_all : display GEMS 4.x series and image headers
-ge4_image : display GEMS 4.x image header
-ge4_series : display GEMS 4.x series header
-ge4_study : display GEMS 4.x study header
ANALYZE info options:
-def_ana_hdr : display the definition of an ANALYZE header
-diff_ana_hdrs : display field differences between 2 headers
-disp_ana_hdr : display ANALYZE headers
-hex : display field values in hexadecimal
-mod_ana_hdr : modify ANALYZE headers
-mod_field : specify a field and value(s) to modify
-prefix : specify an output filename
-overwrite : specify to overwrite the input file(s)
script file options:
-show_bad_all : show lines with whitespace after '\'
This is meant to find problems in script files where the
script programmer has spaces or tabs after a final '\'
on the line. That would break the line continuation.
The -test option is a shorthand version of this one.
-show_bad_backslash : show lines with whitespace after '\'
This is meant to find problems in script files where the
script programmer has spaces or tabs after a final '\'
on the line. That would break the line continuation.
** If the -prefix option is specified, whitespace after
backslashes will be removed in the given output file.
This can also be used in conjunction with -overwrite.
See also -prefix and -overwrite.
-show_bad_char : show any non-printable characters'\'
Sometimes non-visible-but-detrimental characters appear
in scripts due to editors or email programs. This option
helps to point out their presence to the user.
See also -show_bad_all or -test.
-show_file_type : print file type of UNIX, Mac or DOS
Shell scripts need to be UNIX type files. This option
will inform the programmer if there are end of line
characters that define an alternate file type.
-fix_rich_quotes y/n : replace rich-text quotes with ASCII
e.g. -fix_rich_quotes no
Rich text quote values seem to be:
single: 0xe28098 or 0x e28099
double: 0xe2809c or 0x e2809d
In the case of scripts being fixed (e.g. -test -prefix P),
rich-text quote characters will be replaced by ASCII
quotes by default. Use this option to turn off that
behavior.
-test : short for -show_bad_all
Check script files for known issues.
-wrap : apply line wrappers to long lines
-wrap_lines : apply line wrappers to long lines
Try to make the script more readable by adding automatic
line wrappers. Wrapping is done via:
afni_python_wrapper.py -eval 'wrap_file_text()'
* Currently -prefix is not allowed with this option.
-wrap_method METHOD: apply method METHOD for line wrapping
Run as with -wrap_lines, but execute with:
'wrap_file_text(method=METHOD)'
raw ascii options:
-length LENGTH : specify the number of bytes to print/modify
: e.g. -length 17
This includes numbers after the conversion to binary. So
if -mod_data is '2 -63 186', and -mod_type is 'sint2' (or
signed shorts), then 6 bytes will be written (2 bytes for
each of 3 short integers).
** Note that if the -length argument is MORE than what is
needed to write the numbers out, the remaining length of
bytes will be written with zeros. If '17' is given for
the length, and 3 short integers are given as data, there
will be 11 bytes of 0 written after the 6 bytes of data.
-mod_data DATA : specify a string to change the data to
: e.g. -mod_data hello
: e.g. -mod_data '2 -17.4 649'
: e.g. -mod_data "change to this string"
This is the data that will be written into the modified
file. If the -mod_type is 'str' or 'char', then the
output data will be those characters. If the -mod_type
is any other (i.e. a binary numerical format), then the
output will be the -mod_data, converted from numerical
text to binary.
** Note that a list of numbers must be contained in quotes,
so that it will be processed as a single parameter.
-mod_type TYPE : specify the data type to write to the file
: e.g. -mod_type string
: e.g. -mod_type sint2
: e.g. -mod_type float4
: default is 'str'
TYPE can be one of:
str : perform a string substitution
char, val : perform a (repeated?) character substitution
uint1 : single byte unsigned int (binary write)
sint1 : single byte signed int (binary write)
uint2 : two byte unsigned int (binary write)
sint2 : two byte signed int (binary write)
uint4 : four byte unsigned int (binary write)
sint4 : four byte signed int (binary write)
float4 : four byte floating point (binary write)
float8 : eight byte floating point (binary write)
If 'str' is used, which is the default action, the data is
replaced by the contents of the string DATA (from the
'-mod_data' option).
If 'char' is used, then LENGTH bytes are replaced by the
first character of DATA, repeated LENGTH times.
For any of the others, the list of numbers found in the
-mod_data option will be written in the supplied binary
format. LENGTH must be large enough to accommodate this
list. And if LENGTH is higher, the output will be padded
with zeros, to fill to the requested length.
-offset OFFSET : use this offset into each file
: e.g. -offset 100
: default is 0
This is the offset into each file for the data to be
read or modified.
-quiet : do not output header information
numeric options:
-disp_hex : display bytes in hex
-disp_hex1 : display bytes in hex
-disp_hex2 : display 2-byte integers in hex
-disp_hex4 : display 4-byte integers in hex
-disp_int2 : display 2-byte integers
-disp_int4 : display 4-byte integers
-disp_real4 : display 4-byte real numbers
-swap_bytes : use byte-swapping on numbers
If this option is used, then byte swapping is done on any
multi-byte numbers read from or written to the file.
- R Reynolds, version: 3.20 (January 21, 2024), compiled: Oct 31 2024
