Improve opt parsing, and distinguish long from short.

[thirdparty/mdadm.git] / ReadMe.c

diff --git a/ReadMe.c b/ReadMe.c
index 9a33abcb3c15f59b90f3aa308b6d299bb83cac7d..5dae87aae7c719ab2985345d6faa59975da337de 100644 (file)
--- a/ReadMe.c
+++ b/ReadMe.c
@@ -1,7 +1,7 @@
 /*
  * mdadm - manage Linux "md" devices aka RAID arrays.
  *
 /*
  * mdadm - manage Linux "md" devices aka RAID arrays.
  *

- * Copyright (C) 2001-2007 Neil Brown <neilb@suse.de>
+ * Copyright (C) 2001-2010 Neil Brown <neilb@suse.de>

  *
  *
  *    This program is free software; you can redistribute it and/or modify
  *
  *
  *    This program is free software; you can redistribute it and/or modify


@@ -24,7 +24,7 @@
 
 #include "mdadm.h"
 
 
 #include "mdadm.h"
 

-char Version[] = Name " - v2.6.3 - 20th August 2007\n";
+char Version[] = Name " - v3.2-devel - 23rd November 2010\n";

 
 /*
  * File: ReadMe.c
 
 /*
  * File: ReadMe.c


@@ -86,15 +86,15 @@ char Version[] = Name " - v2.6.3 - 20th August 2007\n";
  *     At the time if writing, there is only minimal support.
  */
 
  *     At the time if writing, there is only minimal support.
  */
 

-char short_options[]="-ABCDEFGIQhVXWvqbc:i:l:p:m:n:x:u:c:d:z:U:sarfRSow1tye:";
+char short_options[]="-ABCDEFGIQhVXWZ:vqbc:i:l:p:m:n:x:u:c:d:z:U:N:sarfRSow1tye:";

 char short_bitmap_options[]=
 char short_bitmap_options[]=

-                   "-ABCDEFGIQhVXWvqb:c:i:l:p:m:n:x:u:c:d:z:U:sarfRSow1tye:";
+                   "-ABCDEFGIQhVXWZ:vqb:c:i:l:p:m:n:x:u:c:d:z:U:N:sarfRSow1tye:";

 char short_bitmap_auto_options[]=
 char short_bitmap_auto_options[]=

-                   "-ABCDEFGIQhVXWvqb:c:i:l:p:m:n:x:u:c:d:z:U:sa:rfRSow1tye:";
+                   "-ABCDEFGIQhVXWZ:vqb:c:i:l:p:m:n:x:u:c:d:z:U:N:sa:rfRSow1tye:";

 
 struct option long_options[] = {
 
 struct option long_options[] = {

-    {"manage",    0, 0, '@'},
-    {"misc",      0, 0, '#'},
+    {"manage",    0, 0, ManageOpt},
+    {"misc",      0, 0, MiscOpt},

     {"assemble",  0, 0, 'A'},
     {"build",     0, 0, 'B'},
     {"create",    0, 0, 'C'},
     {"assemble",  0, 0, 'A'},
     {"build",     0, 0, 'B'},
     {"create",    0, 0, 'C'},


@@ -107,82 +107,95 @@ struct option long_options[] = {
     {"query",    0, 0, 'Q'},
     {"examine-bitmap", 0, 0, 'X'},
     {"auto-detect", 0, 0, AutoDetect},
     {"query",    0, 0, 'Q'},
     {"examine-bitmap", 0, 0, 'X'},
     {"auto-detect", 0, 0, AutoDetect},

+    {"detail-platform", 0, 0, DetailPlatform},
+    {"kill-subarray", 1, 0, KillSubarray},
+    {"update-subarray", 1, 0, UpdateSubarray},

 
     /* synonyms */
     {"monitor",   0, 0, 'F'},
 
     /* synonyms */
     {"monitor",   0, 0, 'F'},

-           
+

     /* after those will normally come the name of the md device */
     {"help",      0, 0, 'h'},
     /* after those will normally come the name of the md device */
     {"help",      0, 0, 'h'},

-    {"help-options",0,0,'h'},
+    {"help-options",0,0, HelpOptions},

     {"version",          0, 0, 'V'},
     {"verbose",   0, 0, 'v'},
     {"quiet",    0, 0, 'q'},
 
     /* For create or build: */
     {"version",          0, 0, 'V'},
     {"verbose",   0, 0, 'v'},
     {"quiet",    0, 0, 'q'},
 
     /* For create or build: */

-    {"chunk",    1, 0, 'c'},
-    {"rounding",  1, 0, 'c'}, /* for linear, chunk is really a rounding number */
+    {"chunk",    1, 0, ChunkSize},
+    {"rounding",  1, 0, ChunkSize}, /* for linear, chunk is really a
+                                    * rounding number */

     {"level",     1, 0, 'l'}, /* 0,1,4,5,6,linear */
     {"level",     1, 0, 'l'}, /* 0,1,4,5,6,linear */

-    {"parity",    1, 0, 'p'}, /* {left,right}-{a,}symmetric */
-    {"layout",    1, 0, 'p'},
+    {"parity",    1, 0, Layout}, /* {left,right}-{a,}symmetric */
+    {"layout",    1, 0, Layout},

     {"raid-disks",1, 0, 'n'},
     {"raid-devices",1, 0, 'n'},
     {"spare-disks",1,0, 'x'},
     {"spare-devices",1,0, 'x'},
     {"size",     1, 0, 'z'},
     {"raid-disks",1, 0, 'n'},
     {"raid-devices",1, 0, 'n'},
     {"spare-disks",1,0, 'x'},
     {"spare-devices",1,0, 'x'},
     {"size",     1, 0, 'z'},

-    {"auto",     1, 0, 'a'}, /* also for --assemble */
+    {"auto",     1, 0, Auto}, /* also for --assemble */

     {"assume-clean",0,0, AssumeClean },
     {"metadata",  1, 0, 'e'}, /* superblock format */
     {"assume-clean",0,0, AssumeClean },
     {"metadata",  1, 0, 'e'}, /* superblock format */

-    {"bitmap",   1, 0, 'b'},
+    {"bitmap",   1, 0, Bitmap},

     {"bitmap-chunk", 1, 0, BitmapChunk},
     {"write-behind", 2, 0, WriteBehind},
     {"bitmap-chunk", 1, 0, BitmapChunk},
     {"write-behind", 2, 0, WriteBehind},

-    {"write-mostly",0, 0, 'W'},
+    {"write-mostly",0, 0, WriteMostly},

     {"re-add",    0, 0,  ReAdd},
     {"homehost",  1, 0,  HomeHost},
     {"re-add",    0, 0,  ReAdd},
     {"homehost",  1, 0,  HomeHost},

+#if 0

     {"auto-update-homehost", 0, 0, AutoHomeHost},
     {"auto-update-homehost", 0, 0, AutoHomeHost},

+#endif

     {"symlinks",  1, 0,  Symlinks},
 
     /* For assemble */
     {"uuid",      1, 0, 'u'},
     {"symlinks",  1, 0,  Symlinks},
 
     /* For assemble */
     {"uuid",      1, 0, 'u'},

-    {"super-minor",1,0, 'm'},
+    {"super-minor",1,0, SuperMinor},

     {"name",     1, 0, 'N'},
     {"name",     1, 0, 'N'},

-    {"config",    1, 0, 'c'},
+    {"config",    1, 0, ConfigFile},

     {"scan",      0, 0, 's'},
     {"scan",      0, 0, 's'},

-    {"force",    0, 0, 'f'},
+    {"force",    0, 0, Force},

     {"update",   1, 0, 'U'},
 
     /* Management */
     {"update",   1, 0, 'U'},
 
     /* Management */

-    {"add",       0, 0, 'a'},
-    {"remove",    0, 0, 'r'},
-    {"fail",      0, 0, 'f'},
-    {"set-faulty",0, 0, 'f'},
+    {"add",       0, 0, Add},
+    {"remove",    0, 0, Remove},
+    {"fail",      0, 0, Fail},
+    {"set-faulty",0, 0, Fail},

     {"run",       0, 0, 'R'},
     {"stop",      0, 0, 'S'},
     {"readonly",  0, 0, 'o'},
     {"readwrite", 0, 0, 'w'},
     {"no-degraded",0,0,  NoDegraded },
     {"run",       0, 0, 'R'},
     {"stop",      0, 0, 'S'},
     {"readonly",  0, 0, 'o'},
     {"readwrite", 0, 0, 'w'},
     {"no-degraded",0,0,  NoDegraded },

-    {"wait",     0, 0, 'W'},
+    {"wait",     0, 0,  WaitOpt},
+    {"wait-clean", 0, 0, Waitclean },

 
     /* For Detail/Examine */
 
     /* For Detail/Examine */

-    {"brief",    0, 0, 'b'},
+    {"brief",    0, 0, Brief},

     {"export",   0, 0, 'Y'},
     {"sparc2.2",  0, 0, Sparc22},
     {"test",      0, 0, 't'},
 
     /* For Follow/monitor */
     {"export",   0, 0, 'Y'},
     {"sparc2.2",  0, 0, Sparc22},
     {"test",      0, 0, 't'},
 
     /* For Follow/monitor */

-    {"mail",      1, 0, 'm'},
-    {"program",   1, 0, 'p'},
-    {"alert",     1, 0, 'p'},
+    {"mail",      1, 0, EMail},
+    {"program",   1, 0, ProgramOpt},
+    {"alert",     1, 0, ProgramOpt},
+    {"increment", 1, 0, Increment},

     {"delay",     1, 0, 'd'},
     {"delay",     1, 0, 'd'},

-    {"daemonise", 0, 0, 'f'},
-    {"daemonize", 0, 0, 'f'},
+    {"daemonise", 0, 0, Fork},
+    {"daemonize", 0, 0, Fork},

     {"oneshot",   0, 0, '1'},
     {"pid-file",  1, 0, 'i'},
     {"syslog",    0, 0, 'y'},
     {"oneshot",   0, 0, '1'},
     {"pid-file",  1, 0, 'i'},
     {"syslog",    0, 0, 'y'},

+    {"no-sharing", 0, 0, NoSharing},
+

     /* For Grow */
     {"backup-file", 1,0, BackupFile},
     /* For Grow */
     {"backup-file", 1,0, BackupFile},

+    {"array-size", 1, 0, 'Z'},

 
     /* For Incremental */
 
     /* For Incremental */

-    {"rebuild-map", 0, 0, 'r'},
+    {"rebuild-map", 0, 0, RebuildMapOpt},
+    {"path", 1, 0, IncrementalPath},
+

     {0, 0, 0, 0}
 };
 
     {0, 0, 0, 0}
 };
 


@@ -207,7 +220,7 @@ char Help[] =
 "       mdadm --grow options device\n"
 "            resize/reshape an active array\n"
 "       mdadm --incremental device\n"
 "       mdadm --grow options device\n"
 "            resize/reshape an active array\n"
 "       mdadm --incremental device\n"

-"            add a device to an array as appropriate\n"
+"            add/remove a device to/from an array as appropriate\n"

 "       mdadm --monitor options...\n"
 "            Monitor one or more array for significant changes.\n"
 "       mdadm device options...\n"
 "       mdadm --monitor options...\n"
 "            Monitor one or more array for significant changes.\n"
 "       mdadm device options...\n"


@@ -250,7 +263,7 @@ char OptionHelp[] =
 "  --examine-bitmap -X: Display the detail of a bitmap file\n"
 "  --monitor     -F   : monitor (follow) some arrays\n"
 "  --grow        -G   : resize/ reshape and array\n"
 "  --examine-bitmap -X: Display the detail of a bitmap file\n"
 "  --monitor     -F   : monitor (follow) some arrays\n"
 "  --grow        -G   : resize/ reshape and array\n"

-"  --incremental -I   : add a single device to an array as appropriate\n"
+"  --incremental -I   : add/remove a single device to/from an array as appropriate\n"

 "  --query       -Q   : Display general information about how a\n"
 "                       device relates to the md driver\n"
 "  --auto-detect      : Start arrays auto-detected by the kernel\n"
 "  --query       -Q   : Display general information about how a\n"
 "                       device relates to the md driver\n"
 "  --auto-detect      : Start arrays auto-detected by the kernel\n"


@@ -269,7 +282,6 @@ char OptionHelp[] =
 "  --size=       -z   : Size (in K) of each drive in RAID1/4/5/6/10 - optional\n"
 "  --force       -f   : Honour devices as listed on command line.  Don't\n"
 "                     : insert a missing drive for RAID5.\n"
 "  --size=       -z   : Size (in K) of each drive in RAID1/4/5/6/10 - optional\n"
 "  --force       -f   : Honour devices as listed on command line.  Don't\n"
 "                     : insert a missing drive for RAID5.\n"

-"  --auto(=p)    -a   : Automatically allocate new (partitioned) md array if needed.\n"

 "  --assume-clean     : Assume the array is already in-sync. This is dangerous.\n"
 "  --bitmap-chunk=    : chunksize of bitmap in bitmap file (Kilobytes)\n"
 "  --delay=      -d   : seconds between bitmap updates\n"
 "  --assume-clean     : Assume the array is already in-sync. This is dangerous.\n"
 "  --bitmap-chunk=    : chunksize of bitmap in bitmap file (Kilobytes)\n"
 "  --delay=      -d   : seconds between bitmap updates\n"


@@ -287,7 +299,6 @@ char OptionHelp[] =
 "  --scan        -s   : scan config file for missing information\n"
 "  --force       -f   : Assemble the array even if some superblocks appear out-of-date\n"
 "  --update=     -U   : Update superblock: try '-A --update=?' for list of options.\n"
 "  --scan        -s   : scan config file for missing information\n"
 "  --force       -f   : Assemble the array even if some superblocks appear out-of-date\n"
 "  --update=     -U   : Update superblock: try '-A --update=?' for list of options.\n"

-"  --auto(=p)    -a   : Automatically allocate new (partitioned) md array if needed.\n"

 "  --no-degraded      : Do not start any degraded arrays - default unless --scan.\n"
 "\n"
 " For detail or examine:\n"
 "  --no-degraded      : Do not start any degraded arrays - default unless --scan.\n"
 "\n"
 " For detail or examine:\n"


@@ -465,6 +476,7 @@ char Help_misc[] =
 "  --query       -Q   : Display general information about how a\n"
 "                       device relates to the md driver\n"
 "  --detail      -D   : Display details of an array\n"
 "  --query       -Q   : Display general information about how a\n"
 "                       device relates to the md driver\n"
 "  --detail      -D   : Display details of an array\n"

+"  --detail-platform  : Display hardware/firmware details\n"

 "  --examine     -E   : Examine superblock on an array component\n"
 "  --examine-bitmap -X: Display contents of a bitmap file\n"
 "  --zero-superblock  : erase the MD superblock from a device.\n"
 "  --examine     -E   : Examine superblock on an array component\n"
 "  --examine-bitmap -X: Display contents of a bitmap file\n"
 "  --zero-superblock  : erase the MD superblock from a device.\n"


@@ -492,6 +504,7 @@ char Help_monitor[] =
 "  --mail=       -m   : Address to mail alerts of failure to\n"
 "  --program=    -p   : Program to run when an event is detected\n"
 "  --alert=           : same as --program\n"
 "  --mail=       -m   : Address to mail alerts of failure to\n"
 "  --program=    -p   : Program to run when an event is detected\n"
 "  --alert=           : same as --program\n"

+"  --increment=  -r   : Report RebuildNN events in the given increment. default=20\n"

 "  --delay=      -d   : seconds of delay between polling state. default=60\n"
 "  --config=     -c   : specify a different config file\n"
 "  --scan        -s   : find mail-address/program in config file\n"
 "  --delay=      -d   : seconds of delay between polling state. default=60\n"
 "  --config=     -c   : specify a different config file\n"
 "  --scan        -s   : find mail-address/program in config file\n"


@@ -517,27 +530,38 @@ char Help_grow[] =
 "  --layout=      -p   : For a FAULTY array, set/change the error mode.\n"
 "  --size=        -z   : Change the active size of devices in an array.\n"
 "                      : This is useful if all devices have been replaced\n"
 "  --layout=      -p   : For a FAULTY array, set/change the error mode.\n"
 "  --size=        -z   : Change the active size of devices in an array.\n"
 "                      : This is useful if all devices have been replaced\n"

-"                      : with larger devices.\n"
-"  --raid-disks=  -n   : Change the number of active devices in an array.\n"
-"                      : array.\n"
+"                      : with larger devices.   Value is in Kilobytes, or\n"
+"                      : the special word 'max' meaning 'as large as possible'.\n"
+"  --raid-devices= -n  : Change the number of active devices in an array.\n"

 "  --bitmap=      -b   : Add or remove a write-intent bitmap.\n"
 "  --bitmap=      -b   : Add or remove a write-intent bitmap.\n"

+"  --backup-file= file : A file on a differt device to store data for a\n"
+"                      : short time while increasing raid-devices on a\n"
+"                      : RAID4/5/6 array. Not needed when a spare is present.\n"
+"  --array-size=  -Z   : Change visible size of array.  This does not change\n"
+"                      : any data on the device, and is not stable across restarts.\n"

 ;
 
 char Help_incr[] =
 ;
 
 char Help_incr[] =

-"Usage: mdadm --incremental [-Rqrs] device\n"
+"Usage: mdadm --incremental [-Rqrsf] device\n"

 "\n"
 "This usage allows for incremental assembly of md arrays.  Devices can be\n"
 "added one at a time as they are discovered.  Once an array has all expected\n"
 "devices, it will be started.\n"
 "\n"
 "\n"
 "This usage allows for incremental assembly of md arrays.  Devices can be\n"
 "added one at a time as they are discovered.  Once an array has all expected\n"
 "devices, it will be started.\n"
 "\n"

-"Options that are valid with incremental assembly (-I --incremental) more are:\n"
-"  --run       -R  : run arrays as soon as a minimal number of devices are\n"
-"                  : present rather than waiting for all expected.\n"
-"  --quiet     -q  : Don't print any information messages, just errors.\n"
-"  --rebuild   -r  : Rebuild the 'map' file that mdadm uses for tracking\n"
-"                  : partial arrays.\n"
-"  --scan      -s  : Use with -R to start any arrays that have the minimal\n"
-"                  : required number of devices, but are not yet started.\n"
+"Optionally, the process can be reversed by using the fail option.\n"
+"When fail mode is invoked, mdadm will see if the device belongs to an array\n"
+"and then both fail (if needed) and remove the device from that array.\n"
+"\n"
+"Options that are valid with incremental assembly (-I --incremental) are:\n"
+"  --run         -R : Run arrays as soon as a minimal number of devices are\n"
+"                   : present rather than waiting for all expected.\n"
+"  --quiet       -q : Don't print any information messages, just errors.\n"
+"  --rebuild-map -r : Rebuild the 'map' file that mdadm uses for tracking\n"
+"                   : partial arrays.\n"
+"  --scan        -s : Use with -R to start any arrays that have the minimal\n"
+"                   : required number of devices, but are not yet started.\n"
+"  --fail      -f  : First fail (if needed) and then remove device from\n"
+"                  : any array that it is a member of.\n"

 ;
 
 char Help_config[] =
 ;
 
 char Help_config[] =


@@ -578,21 +602,54 @@ char Help_config[] =
 /* name/number mappings */
 
 mapping_t r5layout[] = {
 /* name/number mappings */
 
 mapping_t r5layout[] = {

-       { "left-asymmetric", 0},
-       { "right-asymmetric", 1},
-       { "left-symmetric", 2},
-       { "right-symmetric", 3},
-
-       { "default", 2},
-       { "la", 0},
-       { "ra", 1},
-       { "ls", 2},
-       { "rs", 3},
+       { "left-asymmetric", ALGORITHM_LEFT_ASYMMETRIC},
+       { "right-asymmetric", ALGORITHM_RIGHT_ASYMMETRIC},
+       { "left-symmetric", ALGORITHM_LEFT_SYMMETRIC},
+       { "right-symmetric", ALGORITHM_RIGHT_SYMMETRIC},
+
+       { "default", ALGORITHM_LEFT_SYMMETRIC},
+       { "la", ALGORITHM_LEFT_ASYMMETRIC},
+       { "ra", ALGORITHM_RIGHT_ASYMMETRIC},
+       { "ls", ALGORITHM_LEFT_SYMMETRIC},
+       { "rs", ALGORITHM_RIGHT_SYMMETRIC},
+
+       { "parity-first", ALGORITHM_PARITY_0},
+       { "parity-last", ALGORITHM_PARITY_N},
+       { "ddf-zero-restart", ALGORITHM_RIGHT_ASYMMETRIC},
+       { "ddf-N-restart", ALGORITHM_LEFT_ASYMMETRIC},
+       { "ddf-N-continue", ALGORITHM_LEFT_SYMMETRIC},
+
+       { NULL, 0}
+};
+mapping_t r6layout[] = {
+       { "left-asymmetric", ALGORITHM_LEFT_ASYMMETRIC},
+       { "right-asymmetric", ALGORITHM_RIGHT_ASYMMETRIC},
+       { "left-symmetric", ALGORITHM_LEFT_SYMMETRIC},
+       { "right-symmetric", ALGORITHM_RIGHT_SYMMETRIC},
+
+       { "default", ALGORITHM_LEFT_SYMMETRIC},
+       { "la", ALGORITHM_LEFT_ASYMMETRIC},
+       { "ra", ALGORITHM_RIGHT_ASYMMETRIC},
+       { "ls", ALGORITHM_LEFT_SYMMETRIC},
+       { "rs", ALGORITHM_RIGHT_SYMMETRIC},
+
+       { "parity-first", ALGORITHM_PARITY_0},
+       { "parity-last", ALGORITHM_PARITY_N},
+       { "ddf-zero-restart", ALGORITHM_ROTATING_ZERO_RESTART},
+       { "ddf-N-restart", ALGORITHM_ROTATING_N_RESTART},
+       { "ddf-N-continue", ALGORITHM_ROTATING_N_CONTINUE},
+
+       { "left-asymmetric-6", ALGORITHM_LEFT_ASYMMETRIC_6},
+       { "right-asymmetric-6", ALGORITHM_RIGHT_ASYMMETRIC_6},
+       { "left-symmetric-6", ALGORITHM_LEFT_SYMMETRIC_6},
+       { "right-symmetric-6", ALGORITHM_RIGHT_SYMMETRIC_6},
+       { "parity-first-6", ALGORITHM_PARITY_0_6},
+

        { NULL, 0}
 };
 
 mapping_t pers[] = {
        { NULL, 0}
 };
 
 mapping_t pers[] = {

-       { "linear", -1},
+       { "linear", LEVEL_LINEAR},

        { "raid0", 0},
        { "0", 0},
        { "stripe", 0},
        { "raid0", 0},
        { "0", 0},
        { "stripe", 0},


@@ -603,13 +660,14 @@ mapping_t pers[] = {
        { "4", 4},
        { "raid5", 5},
        { "5", 5},
        { "4", 4},
        { "raid5", 5},
        { "5", 5},

-       { "multipath", -4},
-       { "mp", -4},
+       { "multipath", LEVEL_MULTIPATH},
+       { "mp", LEVEL_MULTIPATH},

        { "raid6", 6},
        { "6", 6},
        { "raid10", 10},
        { "10", 10},
        { "raid6", 6},
        { "6", 6},
        { "raid10", 10},
        { "10", 10},

-       { "faulty", -5},
+       { "faulty", LEVEL_FAULTY},
+       { "container", LEVEL_CONTAINER},

        { NULL, 0}
 };
 
        { NULL, 0}
 };