migrate(8)						      System Manager's Manual							migrate(8)

NAME

       migrate - Move a file or file pages to another volume in an AdvFS file domain

SYNOPSIS

       /usr/sbin/migrate [-p pageoffset] [-n pagecount] [-s volumeindex] [-d volumeindex] filename

OPTIONS

       Specifies  the  volume  index  number of the volume to which the pages are to be migrated. You can determine the volume index number of the
       volumes in an AdvFS file domain by using the showfile -x command.  If you do not specify the -d option, the AdvFS determines  the  destina-
       tion  of  the file or the file pages.  The AdvFS moves the file or the file pages to any volume or volumes with available space.  Specifies
       the number of pages to migrate, starting at the pageoffset value. The default page count is to EOF.  If you do not specify the  -n  option,
       the  migrate  command  migrates	pages  from  the  pageoffset value to the end of the file.  Specifies the page offset of the first page to
       migrate.  The first page of the file is page 0. The default page offset is 0.  If you do not specify the -p  option,  the  migrate  command
       migrates  pages	starting  at page 0 of the file.  Specifies the volume index number of the volume from which the pages are to be migrated.
       Use the showfile -x command to determine the volume index number of the volumes in an AdvFS file domain.

	      If you specify the -s option and the volume that contains the file does not contain any data  extents  of  that  file,  the  utility
	      returns success without taking any action.

	      You  must  use  the  -s option when you are migrating striped files.  You can move pages of a striped file or a stripe file segment,
	      which is the entire portion of a striped file that resides on the specified volume, to another volume.

OPERANDS

       Specifies the name of the file or file pages to be migrated from the volume. The file can be simple or striped.

DESCRIPTION

       The migrate utility moves the specified simple (unstriped) file to another volume in the same file domain.  The utility also moves pages of
       a simple file or pages of a striped file segment to another volume (or volumes, if necessary) within the file domain.

       Because	there are no read/write restrictions when using this command, you can migrate a file while users are reading it, writing to it, or
       both, without disrupting file I/O. File migration is transparent to users.

       When you run the migrate utility with only the -p and -n options, the utility attempts to allocate destination pages  contiguously  on  one
       destination  volume  in the file domain.  If there are not enough free, contiguous blocks to accomplish the move, the utility then attempts
       to allocate the pages to the next available blocks on the same volume.  If there are not enough free blocks on the same volume, the utility
       then  attempts  to  moves the file to the next available volume or volumes. The utility returns an error diagnostic if it cannot accomplish
       the move.

       You must use the -s, -n, and -p options in order to move pages of a striped file from one volume to another. Only those pages  assigned	to
       the source volume are moved to the destination volume:  all pages in the file are not moved.

       You  can  use  the  migrate  utility  to move heavily accessed files or pages of files to a different volume in the file domain. Use the -d
       option to indicate a specific volume. Also, you can use the utility to defragment a specific file, because the migrate utility  defragments
       a file whenever possible.

NOTES

       The migrate utility does not evaluate your migration decisions.	As a result, you can move more than one striped file segment onto the same
       volume, which can defeat the purpose of striping the file.

       The number of stripes is determined by the number of extent maps for the file although a map may point to more than one volume. If you want
       to change the number of stripes for the file, you must re-create the file with the desired number of stripes.

RESTRICTIONS

       You  can  only perform one migrate operation on the same file at the same time.	When you migrate a striped file, you can only migrate from
       one source volume at a time.

       You must be the root user to use this utility.

EXIT STATUS

       The utility returns a value of 0 (zero) on success, otherwise it returns a nonzero value and an error diagnostic.

EXAMPLES

       The following examples perform tasks using the migrate utility.	To migrate the simple file abc from its current volume to any other volume
       in the file domain, enter: # migrate abc To migrate the simple file abc from volume 1 of a file domain to volume 6 of a file domain, enter:
       # migrate -s 1 -d 6 abc To migrate pages 10 through 99 (that is, 90 pages starting at page 10) of the simple file abc from its current vol-
       ume  to	volume	2  of  the  file domain, enter: # migrate -p 10 -n 90 -d 2 abc The following example migrates all the pages of a file that
       reside on a specified volume. A file, stripe_1, is striped across Volumes 1, 2, and 3 of a six-volume AdvFS file  domain.  To  migrate  the
       entire stripe file segment of the stripe_1 file that is on volume 1 to volume 4 of the domain, enter: # migrate -s 1 -d 4 stripe_1 The fol-
       lowing example moves some, but not all, file pages on one volume of a striped file to another volume in the file domain. Use  the  showfile
       command with the -x flag to determine the volume index, the page count, and the page offset for the volume. Then specify the pages you want
       to migrate.

	      In this example the file str_file is striped across three volumes (1, 2, and 3)	    of a four volume file domain. To move some	of
	      the pages from volume 2 to volume 4, first identify the page offset and the page count for the pages you want to move: # showfile -x
	      str_file
		  Id Vol PgSz Pages XtntType Segs SegSz   I/O Perf File 6.8007	 2   16   123	stripe	  3	8 async  69% str_file

		extentMap: 1
		  pageOff    pageCnt	volIndex    volBlock	blockCnt
			0	   8	       3       67312	     624
		       24	   8
		       48	   8
		       72	   8
		       96	   7
		      103	   1	       3       67952	      64
		      120	   3
		  extentCnt: 2

		extentMap: 2
		  pageOff    pageCnt	volIndex    volBlock	blockCnt
			8	   8	       4       67312	     352
		       32	   8
		       56	   6
		       62	   2	       4       67696	      64
		       80	   2
		       82	   6	       4       67856	      96
		      104	   8	       4       68080	     128
		  extentCnt: 4

		extentMap: 3
		  pageOff    pageCnt	volIndex    volBlock	blockCnt
		       16	   8	       1       76048	     256
		       40	   8
		       64	   8	       1       76320	     128
		       88	   8	       1       76544	     128
		      112	   8	       1       76720	     128
		  extentCnt: 4

	      The showfile output shows that volume 4, as shown in extent map 2, contains a total of 40 pages of the striped file starting at page
	      offset  8.   You	want to migrate the first 16 pages that reside on volume 4 to volume 2. The first eight pages to be moved start at
	      page offset 8 and end at page offset 15. The next eight pages to be moved start at page offset 32 and end at page offset 39. So  the
	      range  of  pages	you want to move (the value of the -n flag) is 32 pages; that is, 8 to 39 inclusive. (The other pages in the range
	      are on other volumes because the file is striped.) The command will migrate only the pages from the specified volume in  the  speci-
	      fied range.  # migrate -p 8 -n 32 -s 4 -d 2 str_file

	      Because  you  did not move all of the pages from volume 4 to volume 2, the file is now stored on four volumes.  Note, that this does
	      not change the stripe width of the file. There are still three extent maps.

	      To confirm the migration, reissue the showfile command. Following is part of the output showing the new extent map 2:
		extentMap: 2
		  pageOff    pageCnt	volIndex    volBlock	blockCnt
			8	   8	       2       51920	     256
		       32	   8
		       56	   8	       4       68592	     256
		       80	   8
		      104	   8	       4       68080	     128
		  extentCnt: 4

SEE ALSO

       Commands: showfdmn(8), showfile(8), stripe(8)

       Files: advfs(4)

																	migrate(8)