:orphan: .. _ahelp_file_tool: ********* file_tool ********* .. contents:: :local: | .. code-block:: none 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: Apr 23 2024