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