lustre/doc/llapi_hsm_state_get.3

   1 .TH lustreapi 3 "2014 Sep 22" Lustre "Lustre Application Interface Library"
   2 .SH NAME
   3 llapi_hsm_state_get, llapi_hsm_state_get_fd \- get HSM state
   4 information for a file on a Lustre filesystem
   5 .SH SYNOPSIS
   6 .nf
   7 .B #include <lustre/lustreapi.h>
   8 .sp
   9 .BI "int llapi_hsm_state_get(const char *" path ", struct hsm_user_state *" hus ");"
  10 .sp
  11 .BI "int llapi_hsm_state_get_fd(int " fd ", struct hsm_user_state *" hus ");"
  12 .sp
  13 .fi
  14 .SH DESCRIPTION
  15 .LP
  16 These functions return the HSM state flags and HSM archive ID for the
  17 file referred to by
  18 .IR path
  19 or
  20 .IR fd .
  21 Information is returned in the
  22 .I hus
  23 argument which should already be allocated.
  24 .nf
  25 .LP
  26 struct hsm_user_state {
  27         __u32   hus_states;
  28         __u32   hus_archive_id;
  29 };
  30 .fi
  31 .TP 7
  32 .I hus_archive_id
  33 External HSM archive ID associated with this file.
  34 .TP
  35 .I hus_states
  36 Flag mask for different HSM states and policy hints.
  37 .LP
  38
  39 The value of
  40 .I hus_states
  41 is formed by bitwise or'ing the following possible states:
  42
  43 .TP 7
  44 .B HS_EXISTS
  45 The file has been assigned to an archive and provided to the backend
  46 for archiving. Partial copies may exist in the HSM archive and will
  47 need to be deleted when the file is removed.
  48 .TP
  49 .B HS_DIRTY
  50 The file content is not in sync with the HSM archive. This flag is
  51 set automatically when a file with HS_EXISTS set is changed, and can
  52 be set explicitly by a user.
  53 .TP
  54 .B HS_RELEASED
  55 The file content is not present in Lustre, and must be restored from
  56 the HSM archive before the file can be accessed. File must also be
  57 HS_ARCHIVED state and not HS_DIRTY.
  58 .TP
  59 .B HS_ARCHIVED
  60 A complete copy of the file content exists in the HSM archive.
  61 .TP
  62 .B HS_NORELEASE
  63 This flag indicates the file content should never be released. File
  64 content will stay in Lustre even if a copy exists in HSM backend.
  65 This can be set by a user.
  66 .TP
  67 .B HS_NOARCHIVE
  68 The file will not be archived. This might be used for a large temporary
  69 file, for example. This can be set by a user.
  70 .TP
  71 .B HS_LOST
  72 The file content in the archive is not available, and file can not be
  73 restored. If this file is also HS_RELEASED, then attempts to access
  74 the file will fail. This flag can be set by an administrator.
  75
  76 .SH RETURN VALUES
  77 .LP
  78 .B llapi_hsm_state_get(\|)
  79 and
  80 .B llapi_hsm_state_get_fd(\|)
  81 return:
  82 .TP 7
  83 .B 0
  84 on success
  85 .TP
  86 .B -errno
  87 on failure
  88 .SH ERRORS
  89 .TP 7
  90 .SM ENOMEM
  91 failed to allocate memory.
  92 .TP
  93 .SM ENAMETOOLONG
  94 .I path
  95 was too long.
  96 .TP
  97 .SM ENOENT
  98 .I path
  99 does not point to a file or a directory.
 100 .TP
 101 .SM ENOTTY
 102 .I path
 103 does not point to a Lustre filesystem.
 104 .SH EXAMPLE
 105 .nf
 106 #include <stdlib.h>
 107 #include <stdio.h>
 108 #include <errno.h>
 109
 110 #include <lustre/lustreapi.h>
 111
 112 int main(int argc, char **argv)
 113 {
 114         struct hsm_user_state hus;
 115         int rc;
 116
 117         if (argc < 2) {
 118                 fprintf(stderr, "usage: prog FILEPATH\\n");
 119                 exit(1);
 120         }
 121
 122         rc = llapi_hsm_state_get(argv[1], &hus);
 123         if (rc) {
 124                 fprintf(stderr, "can't get hsm state for %s: %s\\n",
 125                         argv[1], strerror(-rc));
 126                 exit(rc);
 127         }
 128
 129         if (hus.hus_states & HS_RELEASED)
 130                 printf(" released");
 131         if (hus.hus_states & HS_EXISTS)
 132                 printf(" exists");
 133         if (hus.hus_states & HS_ARCHIVED)
 134                 printf(" archived");
 135
 136         /* Display settable flags */
 137         if (hus.hus_states & HS_NORELEASE)
 138                 printf(" never_release");
 139         if (hus.hus_states & HS_NOARCHIVE)
 140                 printf(" never_archive");
 141         if (hus.hus_states & HS_DIRTY)
 142                 printf(" dirty");
 143         if (hus.hus_states & HS_LOST)
 144                 printf(" lost_from_hsm");
 145
 146         if (hus.hus_archive_id != 0)
 147                 printf(", archive_id:%d", hus.hus_archive_id);
 148
 149         printf("\\n");
 150
 151         exit(0);
 152 }
 153 .fi
 154 .SH "SEE ALSO"
 155 .BR lustre (7),
 156 .BR lustreapi (7),
 157 .BR llapi_hsm_state_set (3),
 158 .BR llapi_hsm_state_set_fd (3),
 159 .BR lfs-hsm (1)