--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/PLMN-list-commands	Sun Mar 14 07:57:09 2021 +0000
@@ -0,0 +1,50 @@
+GSM SIM specs define EF_PLMNsel and EF_FPLMN as containing lists of preferred
+and forbidden PLMNs, respectively.  Both files are defined as writable by
+ordinary users, requiring only CHV1 access for both reading and writing - and
+both files are indeed user-writable on Grcard and Sysmocom SIMs.  However, some
+operator-issued SIMs (specifically T-Mobile USA) implement an underhanded trick:
+whenever we try to write anything to either of these two files, the write
+operation appears to succeed (SW 0x9000), but the byte content of the SIM file
+remains unchanged.  Therefore, writability of these files by ordinary end users
+on regular operator-issued SIMs should be regarded as questionable.
+
+fc-simtool provides high-level commands for both dumping (reading) and writing
+both EF_PLMNsel and EF_FPLMN.  Here are the commands for EF_PLMNsel:
+
+plmnsel-dump
+
+This command dumps the full content of EF_PLMNsel.
+
+plmnsel-write index mcc-mnc
+
+This command writes a single entry into EF_PLMNsel.  The first argument is the
+0-based index of the entry position to write into, and the second argument is
+the PLMN code as in MCC-MNC.
+
+plmnsel-write-list plmn-list-file
+
+This command overwrites the entire EF_PLMNsel SIM file with a user-specified
+PLMN list given in an ASCII data file.  The file must contain PLMN codes
+(MCC-MNC) separated by white space; any lines or line tails beginning with '#'
+are treated as comments.  Output from a previous plmnsel-dump is acceptable
+input to plmnsel-write-list.  PLMN codes are written into EF_PLMNsel from index
+0 onward; any unused space at the end is filled with FF bytes.
+
+plmnsel-erase start-index [end-index]
+
+This command erases a single entry position or a range of entry positions in
+EF_PLMNsel.  Because EF_PLMNsel is a transparent EF (not record-based) at the
+SIM protocol level, our numbering of entry positions in this file is 0-based,
+rather than the 1-based convention used for record-based SIM files.  Keyword
+"end" may be specified instead of the final index, meaning erase to the end of
+the file.
+
+plmnsel-erase-all
+
+This command overwrites the entire EF_PLMNsel SIM file with FF bytes,
+corresponding to fully erased state.  This command is more efficient than
+'plmnsel-erase 0 end', as the operation is performed with a single UPDATE BINARY
+SIM protocol command.
+
+The commands for EF_FPLMN parallel those for EF_PLMNsel: simply replace
+plmnsel-* with fplmn-*; all arguments are the same.