migrate(8)migrate(8)NAMEmigrate - 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 vol‐
umes in an AdvFS file domain by using the showfile -x command. If you
do not specify the -d option, the AdvFS determines the destination 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 com‐
mand 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.
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. When
direct I/O is enabled, the migrate operation may experience interrupts.
In all other cases the migrate operation executes without disrupting
file I/O.
When you run the migrate utility with only the -p and -n options, the
utility attempts to allocate destination pages contiguously on one des‐
tination volume in the file domain. If there are not enough free, con‐
tiguous 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 when‐
ever 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 volume 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 following 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 vol‐
umes (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 specified 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 vol‐
ume 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. Follow‐
ing 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)