Update examples

hakavlad · Mar 30, 2024 · 04887d1 · 04887d1
1 parent c5ba3bf
commit 04887d1
Show file tree

Hide file tree

Showing 2 changed files with 160 additions and 3 deletions.
diff --git a/docs/examples/8.md b/docs/examples/8.md
@@ -1,6 +1,12 @@
 
 ## Create files with uniform random data
 
+Random data files can be used as keyfiles and as containers (for embedding cryptoblobs into them) (and for any other arbitrary purposes, of course).
+
+You can create files with random data of any size by selecting option 8 in the menu.
+
+Next, you need to enter the path to the file to be created and the desired size.
+
 #### Create an empty file:
 
 ```
@@ -25,7 +31,7 @@ I: written 0 B
 I: action is completed
 ```
 
-#### Create an empty file with debug:
+#### Create an empty file with debug messages enabled:
 
 ```
 $ tird -d
@@ -79,7 +85,7 @@ I: written 1000 B, 100.0% in 0.0s, avg 13.1 MiB/s
 I: action is completed
 ```
 
-#### Create 1 kB file with debug:
+#### Create 1 kB file with debug messages enabled:
 
 ```
 $ tird -d
@@ -134,7 +140,7 @@ I: written 1000000000 B, 953.7 MiB, 100.0% in 7.6s, avg 126.0 MiB/s
 I: action is completed
 ```
 
-#### Create 2 GB file with debug:
+#### Create 2 GB file with debug messages enabled:
 
 ```
 $ tird -d

diff --git a/docs/examples/9.md b/docs/examples/9.md
@@ -0,0 +1,151 @@
+
+## Overwrite file contents with uniform random data
+
+`tird` can partially or completely overwrite the contents of files with random data.
+
+You can select positions in the file between which the contents will be overwritten with random data.
+
+#### Overwrite the entire 1 MB file contents with random bytes:
+
+```
+$ tird
+
+                       MENU
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    0. Exit              1. Show info
+    2. Encrypt           3. Decrypt
+    4. Embed             5. Extract
+    6. Encrypt & embed   7. Extract & decrypt
+    8. Create w/ random  9. Overwrite w/ random
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[01] Select an option [0-9]: 9
+I: action #9: overwrite file contents with random bytes
+[07] File to overwrite: 1MB
+I: path: "1MB"; size: 1000000 B, 976.6 KiB
+[08] Initial position, valid values are [0; 1000000], default=0: 
+I: initial position: 0
+[09] Final position, valid values are [0; 1000000], default=1000000: 
+I: final position: 1000000
+I: data size to write: 1000000 B, 976.6 KiB
+W: output file will be partially overwritten with random bytes
+[13] Proceed? (Y/N): y
+I: writing...
+I: written 1000000 B, 976.6 KiB, 100.0% in 0.0s, avg 111.6 MiB/s
+I: fsyncing...
+I: fsynced in 0.0s
+I: action is completed
+```
+
+#### Overwrite the entire 1 MB file contents with random bytes with debug messages enabled:
+
+```
+$ tird -d
+W: debug messages enabled!
+
+                       MENU
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    0. Exit              1. Show info
+    2. Encrypt           3. Decrypt
+    4. Embed             5. Extract
+    6. Encrypt & embed   7. Extract & decrypt
+    8. Create w/ random  9. Overwrite w/ random
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[01] Select an option [0-9]: 9
+I: action #9: overwrite file contents with random bytes
+[07] File to overwrite: 1MB
+D: real path: "/tmpfs/1MB"
+D: opening file "1MB" in mode "rb+"
+D: opened file (object): <_io.BufferedRandom name='1MB'>
+I: path: "1MB"; size: 1000000 B, 976.6 KiB
+[08] Initial position, valid values are [0; 1000000], default=0: 
+I: initial position: 0
+[09] Final position, valid values are [0; 1000000], default=1000000: 
+I: final position: 1000000
+I: data size to write: 1000000 B, 976.6 KiB
+W: output file will be partially overwritten with random bytes
+[13] Proceed? (Y/N): Y
+D: current position: of=0
+D: move to position 0 in <_io.BufferedRandom name='1MB'>
+D: current position: of=0
+I: writing...
+D: current position: of=1000000
+I: written 1000000 B, 976.6 KiB, 100.0% in 0.0s, avg 108.1 MiB/s
+I: fsyncing...
+I: fsynced in 0.0s
+D: closing <_io.BufferedRandom name='1MB'>
+D: <_io.BufferedRandom name='1MB'> closed
+I: action is completed
+```
+
+#### Overwriting file contents with random data between positions 1000 and 3000 (writing 2000 random bytes):
+
+```
+$ tird
+
+                       MENU
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    0. Exit              1. Show info
+    2. Encrypt           3. Decrypt
+    4. Embed             5. Extract
+    6. Encrypt & embed   7. Extract & decrypt
+    8. Create w/ random  9. Overwrite w/ random
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[01] Select an option [0-9]: 9
+I: action #9: overwrite file contents with random bytes
+[07] File to overwrite: 1MB
+I: path: "1MB"; size: 1000000 B, 976.6 KiB
+[08] Initial position, valid values are [0; 1000000], default=0: 1000
+I: initial position: 1000
+[09] Final position, valid values are [1000; 1000000], default=1000000: 3000
+I: final position: 3000
+I: data size to write: 2000 B, 2.0 KiB
+W: output file will be partially overwritten with random bytes
+[13] Proceed? (Y/N): 1
+I: writing...
+I: written 2000 B, 2.0 KiB, 100.0% in 0.0s, avg 28.2 MiB/s
+I: fsyncing...
+I: fsynced in 0.0s
+I: action is completed
+```
+
+#### Overwriting file contents with random data between positions 10000 and 50000 (writing 40000 random bytes) with debug messages enabled:
+
+```
+$ tird -d
+W: debug messages enabled!
+
+                       MENU
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    0. Exit              1. Show info
+    2. Encrypt           3. Decrypt
+    4. Embed             5. Extract
+    6. Encrypt & embed   7. Extract & decrypt
+    8. Create w/ random  9. Overwrite w/ random
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+[01] Select an option [0-9]: 9
+I: action #9: overwrite file contents with random bytes
+[07] File to overwrite: 1MB
+D: real path: "/tmpfs/1MB"
+D: opening file "1MB" in mode "rb+"
+D: opened file (object): <_io.BufferedRandom name='1MB'>
+I: path: "1MB"; size: 1000000 B, 976.6 KiB
+[08] Initial position, valid values are [0; 1000000], default=0: 10000
+I: initial position: 10000
+[09] Final position, valid values are [10000; 1000000], default=1000000: 50000
+I: final position: 50000
+I: data size to write: 40000 B, 39.1 KiB
+W: output file will be partially overwritten with random bytes
+[13] Proceed? (Y/N): y
+D: current position: of=0
+D: move to position 10000 in <_io.BufferedRandom name='1MB'>
+D: current position: of=10000
+I: writing...
+D: current position: of=50000
+I: written 40000 B, 39.1 KiB, 100.0% in 0.0s, avg 83.2 MiB/s
+I: fsyncing...
+I: fsynced in 0.0s
+D: closing <_io.BufferedRandom name='1MB'>
+D: <_io.BufferedRandom name='1MB'> closed
+I: action is completed
+```
+