lustre/doc/llapi_hsm_state_get.3

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