Debian Codegraph @

doc/rst/util.rst

raw
1 .. _util.h:
2
3 **util.h**
4
5
6 libnvme utility functions
7
8
9
10 .. c:type:: enum nvme_connect_err
11
12 nvme connect error codes
13
14 **Constants**
15
16 ``ENVME_CONNECT_RESOLVE``
17 failed to resolve host
18
19 ``ENVME_CONNECT_ADDRFAM``
20 unrecognized address family
21
22 ``ENVME_CONNECT_TRADDR``
23 failed to get traddr
24
25 ``ENVME_CONNECT_TARG``
26 need a transport (-t) argument
27
28 ``ENVME_CONNECT_AARG``
29 need a address (-a) argument
30
31 ``ENVME_CONNECT_OPEN``
32 failed to open nvme-fabrics device
33
34 ``ENVME_CONNECT_WRITE``
35 failed to write to nvme-fabrics device
36
37 ``ENVME_CONNECT_READ``
38 failed to read from nvme-fabrics device
39
40 ``ENVME_CONNECT_PARSE``
41 failed to parse ctrl info
42
43 ``ENVME_CONNECT_INVAL_TR``
44 invalid transport type
45
46 ``ENVME_CONNECT_LOOKUP_SUBSYS_NAME``
47 failed to lookup subsystem name
48
49 ``ENVME_CONNECT_LOOKUP_SUBSYS``
50 failed to lookup subsystem
51
52 ``ENVME_CONNECT_ALREADY``
53 the connect attempt failed, already connected
54
55 ``ENVME_CONNECT_INVAL``
56 invalid arguments/configuration
57
58 ``ENVME_CONNECT_ADDRINUSE``
59 hostnqn already in use
60
61 ``ENVME_CONNECT_NODEV``
62 invalid interface
63
64 ``ENVME_CONNECT_OPNOTSUPP``
65 not supported
66
67 ``ENVME_CONNECT_CONNREFUSED``
68 connection refused
69
70 ``ENVME_CONNECT_ADDRNOTAVAIL``
71 cannot assign requested address
72
73 ``ENVME_CONNECT_IGNORED``
74 connect attempt is ignored due to configuration
75
76 ``ENVME_CONNECT_NOKEY``
77 the TLS key is missing
78
79
80 .. c:function:: __u8 nvme_status_to_errno (int status, bool fabrics)
81
82 Converts nvme return status to errno
83
84 **Parameters**
85
86 ``int status``
87 Return status from an nvme passthrough command
88
89 ``bool fabrics``
90 Set to true if :c:type:`status` is to a fabrics target.
91
92 **Return**
93
94 An errno representing the nvme status if it is an nvme status field,
95 or unchanged status is < 0 since errno is already set.
96
97
98 .. c:function:: const char * nvme_status_to_string (int status, bool fabrics)
99
100 Returns string describing nvme return status.
101
102 **Parameters**
103
104 ``int status``
105 Return status from an nvme passthrough command
106
107 ``bool fabrics``
108 Set to true if :c:type:`status` is to a fabrics target.
109
110 **Return**
111
112 String representation of the nvme status if it is an nvme status field,
113 or a standard errno string if status is < 0.
114
115
116 .. c:function:: const char * nvme_errno_to_string (int err)
117
118 Returns string describing nvme connect failures
119
120 **Parameters**
121
122 ``int err``
123 Returned error code from nvme_add_ctrl()
124
125 **Return**
126
127 String representation of the nvme connect error codes
128
129
130 .. c:function:: void nvme_init_ctrl_list (struct nvme_ctrl_list *cntlist, __u16 num_ctrls, __u16 *ctrlist)
131
132 Initialize an nvme_ctrl_list structure from an array.
133
134 **Parameters**
135
136 ``struct nvme_ctrl_list *cntlist``
137 The controller list structure to initialize
138
139 ``__u16 num_ctrls``
140 The number of controllers in the array, :c:type:`ctrlist`.
141
142 ``__u16 *ctrlist``
143 An array of controller identifiers in CPU native endian.
144
145 **Description**
146
147 This is intended to be used with any command that takes a controller list
148 argument. See nvme_ns_attach_ctrls() and nvme_ns_detach().
149
150
151 .. c:function:: void nvme_init_dsm_range (struct nvme_dsm_range *dsm, __u32 *ctx_attrs, __u32 *llbas, __u64 *slbas, __u16 nr_ranges)
152
153 Constructs a data set range structure
154
155 **Parameters**
156
157 ``struct nvme_dsm_range *dsm``
158 DSM range array
159
160 ``__u32 *ctx_attrs``
161 Array of context attributes
162
163 ``__u32 *llbas``
164 Array of length in logical blocks
165
166 ``__u64 *slbas``
167 Array of starting logical blocks
168
169 ``__u16 nr_ranges``
170 The size of the dsm arrays
171
172 **Description**
173
174 Each array must be the same size of size 'nr_ranges'. This is intended to be
175 used with constructing a payload for nvme_dsm().
176
177 **Return**
178
179 The nvme command status if a response was received or -errno
180 otherwise.
181
182
183 .. c:function:: void nvme_init_copy_range (struct nvme_copy_range *copy, __u16 *nlbs, __u64 *slbas, __u32 *eilbrts, __u32 *elbatms, __u32 *elbats, __u16 nr)
184
185 Constructs a copy range structure
186
187 **Parameters**
188
189 ``struct nvme_copy_range *copy``
190 Copy range array
191
192 ``__u16 *nlbs``
193 Number of logical blocks
194
195 ``__u64 *slbas``
196 Starting LBA
197
198 ``__u32 *eilbrts``
199 Expected initial logical block reference tag
200
201 ``__u32 *elbatms``
202 Expected logical block application tag mask
203
204 ``__u32 *elbats``
205 Expected logical block application tag
206
207 ``__u16 nr``
208 Number of descriptors to construct
209
210
211 .. c:function:: void nvme_init_copy_range_f1 (struct nvme_copy_range_f1 *copy, __u16 *nlbs, __u64 *slbas, __u64 *eilbrts, __u32 *elbatms, __u32 *elbats, __u16 nr)
212
213 Constructs a copy range f1 structure
214
215 **Parameters**
216
217 ``struct nvme_copy_range_f1 *copy``
218 Copy range array
219
220 ``__u16 *nlbs``
221 Number of logical blocks
222
223 ``__u64 *slbas``
224 Starting LBA
225
226 ``__u64 *eilbrts``
227 Expected initial logical block reference tag
228
229 ``__u32 *elbatms``
230 Expected logical block application tag mask
231
232 ``__u32 *elbats``
233 Expected logical block application tag
234
235 ``__u16 nr``
236 Number of descriptors to construct
237
238
239 .. c:function:: void nvme_init_copy_range_f2 (struct nvme_copy_range_f2 *copy, __u32 *snsids, __u16 *nlbs, __u64 *slbas, __u16 *sopts, __u32 *eilbrts, __u32 *elbatms, __u32 *elbats, __u16 nr)
240
241 Constructs a copy range f2 structure
242
243 **Parameters**
244
245 ``struct nvme_copy_range_f2 *copy``
246 Copy range array
247
248 ``__u32 *snsids``
249 Source namespace identifier
250
251 ``__u16 *nlbs``
252 Number of logical blocks
253
254 ``__u64 *slbas``
255 Starting LBA
256
257 ``__u16 *sopts``
258 Source options
259
260 ``__u32 *eilbrts``
261 Expected initial logical block reference tag
262
263 ``__u32 *elbatms``
264 Expected logical block application tag mask
265
266 ``__u32 *elbats``
267 Expected logical block application tag
268
269 ``__u16 nr``
270 Number of descriptors to construct
271
272
273 .. c:function:: void nvme_init_copy_range_f3 (struct nvme_copy_range_f3 *copy, __u32 *snsids, __u16 *nlbs, __u64 *slbas, __u16 *sopts, __u64 *eilbrts, __u32 *elbatms, __u32 *elbats, __u16 nr)
274
275 Constructs a copy range f3 structure
276
277 **Parameters**
278
279 ``struct nvme_copy_range_f3 *copy``
280 Copy range array
281
282 ``__u32 *snsids``
283 Source namespace identifier
284
285 ``__u16 *nlbs``
286 Number of logical blocks
287
288 ``__u64 *slbas``
289 Starting LBA
290
291 ``__u16 *sopts``
292 Source options
293
294 ``__u64 *eilbrts``
295 Expected initial logical block reference tag
296
297 ``__u32 *elbatms``
298 Expected logical block application tag mask
299
300 ``__u32 *elbats``
301 Expected logical block application tag
302
303 ``__u16 nr``
304 Number of descriptors to construct
305
306
307 .. c:function:: int nvme_get_feature_length (int fid, __u32 cdw11, __u32 *len)
308
309 Retreive the command payload length for a specific feature identifier
310
311 **Parameters**
312
313 ``int fid``
314 Feature identifier, see :c:type:`enum nvme_features_id <nvme_features_id>`.
315
316 ``__u32 cdw11``
317 The cdw11 value may affect the transfer (only known fid is
318 ``NVME_FEAT_FID_HOST_ID``)
319
320 ``__u32 *len``
321 On success, set to this features payload length in bytes.
322
323 **Return**
324
325 0 on success, -1 with errno set to EINVAL if the function did not
326 recognize :c:type:`fid`.
327
328
329 .. c:function:: int nvme_get_feature_length2 (int fid, __u32 cdw11, enum nvme_data_tfr dir, __u32 *len)
330
331 Retreive the command payload length for a specific feature identifier
332
333 **Parameters**
334
335 ``int fid``
336 Feature identifier, see :c:type:`enum nvme_features_id <nvme_features_id>`.
337
338 ``__u32 cdw11``
339 The cdw11 value may affect the transfer (only known fid is
340 ``NVME_FEAT_FID_HOST_ID``)
341
342 ``enum nvme_data_tfr dir``
343 Data transfer direction: false - host to controller, true -
344 controller to host may affect the transfer (only known fid is
345 ``NVME_FEAT_FID_HOST_MEM_BUF``).
346
347 ``__u32 *len``
348 On success, set to this features payload length in bytes.
349
350 **Return**
351
352 0 on success, -1 with errno set to EINVAL if the function did not
353 recognize :c:type:`fid`.
354
355
356 .. c:function:: int nvme_get_directive_receive_length (enum nvme_directive_dtype dtype, enum nvme_directive_receive_doper doper, __u32 *len)
357
358 Get directive receive length
359
360 **Parameters**
361
362 ``enum nvme_directive_dtype dtype``
363 Directive type, see :c:type:`enum nvme_directive_dtype <nvme_directive_dtype>`
364
365 ``enum nvme_directive_receive_doper doper``
366 Directive receive operation, see :c:type:`enum nvme_directive_receive_doper <nvme_directive_receive_doper>`
367
368 ``__u32 *len``
369 On success, set to this directives payload length in bytes.
370
371 **Return**
372
373 0 on success, -1 with errno set to EINVAL if the function did not
374 recognize :c:type:`dtype` or :c:type:`doper`.
375
376
377 .. c:function:: size_t get_entity_name (char *buffer, size_t bufsz)
378
379 Get Entity Name (ENAME).
380
381 **Parameters**
382
383 ``char *buffer``
384 The buffer where the ENAME will be saved as an ASCII string.
385
386 ``size_t bufsz``
387 The size of **buffer**.
388
389 **Description**
390
391 Per TP8010, ENAME is defined as the name associated with the host (i.e.
392 hostname).
393
394 **Return**
395
396 Number of characters copied to **buffer**.
397
398
399 .. c:function:: size_t get_entity_version (char *buffer, size_t bufsz)
400
401 Get Entity Version (EVER).
402
403 **Parameters**
404
405 ``char *buffer``
406 The buffer where the EVER will be saved as an ASCII string.
407
408 ``size_t bufsz``
409 The size of **buffer**.
410
411 **Description**
412
413 EVER is defined as the operating system name and version as an ASCII
414 string. This function reads different files from the file system and
415 builds a string as follows: [os type] [os release] [distro release]
416
417 E.g. "Linux 5.17.0-rc1 SLES 15.4"
418
419 **Return**
420
421 Number of characters copied to **buffer**.
422
423
424 .. c:function:: char * kv_strip (char *kv)
425
426 Strip blanks from key value string
427
428 **Parameters**
429
430 ``char *kv``
431 The key-value string to strip
432
433 **Description**
434
435 Strip leading/trailing blanks as well as trailing comments from the
436 Key=Value string pointed to by **kv**.
437
438 **Return**
439
440 A pointer to the stripped string. Note that the original string,
441 **kv**, gets modified.
442
443
444 .. c:function:: char * kv_keymatch (const char *kv, const char *key)
445
446 Look for key in key value string
447
448 **Parameters**
449
450 ``const char *kv``
451 The key=value string to search for the presence of **key**
452
453 ``const char *key``
454 The key to look for
455
456 **Description**
457
458 Look for **key** in the Key=Value pair pointed to by **k** and return a
459 pointer to the Value if **key** is found.
460
461 Check if **kv** starts with **key**. If it does then make sure that we
462 have a whole-word match on the **key**, and if we do, return a pointer
463 to the first character of value (i.e. skip leading spaces, tabs,
464 and equal sign)
465
466 **Return**
467
468 A pointer to the first character of "value" if a match is found.
469 NULL otherwise.
470
471
472 .. c:function:: char * startswith (const char *s, const char *prefix)
473
474 Checks that a string starts with a given prefix.
475
476 **Parameters**
477
478 ``const char *s``
479 The string to check
480
481 ``const char *prefix``
482 A string that **s** could be starting with
483
484 **Return**
485
486 If **s** starts with **prefix**, then return a pointer within **s** at
487 the first character after the matched **prefix**. NULL otherwise.
488
489
490 .. c:function:: round_up (val, mult)
491
492 Round a value **val** to the next multiple specified by **mult**.
493
494 **Parameters**
495
496 ``val``
497 Value to round
498
499 ``mult``
500 Multiple to round to.
501
502 **Description**
503
504 usage: int x = round_up(13, sizeof(__u32)); // 13 -> 16
505
506
507 .. c:function:: __u16 nvmf_exat_len (size_t val_len)
508
509 Return length rounded up by 4
510
511 **Parameters**
512
513 ``size_t val_len``
514 Value length
515
516 **Description**
517
518 Return the size in bytes, rounded to a multiple of 4 (e.g., size of
519 __u32), of the buffer needed to hold the exat value of size
520 **val_len**.
521
522 **Return**
523
524 Length rounded up by 4
525
526
527 .. c:function:: __u16 nvmf_exat_size (size_t val_len)
528
529 Return min aligned size to hold value
530
531 **Parameters**
532
533 ``size_t val_len``
534 This is the length of the data to be copied to the "exatval"
535 field of a "struct nvmf_ext_attr".
536
537 **Description**
538
539 Return the size of the "struct nvmf_ext_attr" needed to hold
540 a value of size **val_len**.
541
542 **Return**
543
544 The size in bytes, rounded to a multiple of 4 (i.e. size of
545 __u32), of the "struct nvmf_ext_attr" required to hold a string of
546 length **val_len**.
547
548
549 .. c:function:: struct nvmf_ext_attr * nvmf_exat_ptr_next (struct nvmf_ext_attr *p)
550
551 Increment **p** to the next element in the array.
552
553 **Parameters**
554
555 ``struct nvmf_ext_attr *p``
556 Pointer to an element of an array of "struct nvmf_ext_attr".
557
558 **Description**
559
560 Extended attributes are saved to an array of "struct nvmf_ext_attr"
561 where each element of the array is of variable size. In order to
562 move to the next element in the array one must increment the
563 pointer to the current element (**p**) by the size of the current
564 element.
565
566 **Return**
567
568 Pointer to the next element in the array.
569
570
571
572
573 .. c:type:: enum nvme_version
574
575 Selector for version to be returned by **nvme_get_version**
576
577 **Constants**
578
579 ``NVME_VERSION_PROJECT``
580 Project release version
581
582 ``NVME_VERSION_GIT``
583 Git reference
584
585
586 .. c:function:: const char * nvme_get_version (enum nvme_version type)
587
588 Return version libnvme string
589
590 **Parameters**
591
592 ``enum nvme_version type``
593 Selects which version type (see **struct** nvme_version)
594
595 **Return**
596
597 Returns version string for known types or else "n/a"
598
599
600 .. c:function:: int nvme_uuid_to_string (unsigned char uuid[NVME_UUID_LEN], char *str)
601
602 Return string represenation of encoded UUID
603
604 **Parameters**
605
606 ``unsigned char uuid[NVME_UUID_LEN]``
607 Binary encoded input UUID
608
609 ``char *str``
610 Output string represenation of UUID
611
612 **Return**
613
614 Returns error code if type conversion fails.
615
616
617 .. c:function:: int nvme_uuid_from_string (const char *str, unsigned char uuid[NVME_UUID_LEN])
618
619 Return encoded UUID represenation of string UUID
620
621 **Parameters**
622
623 ``const char *str``
624 Output string represenation of UUID
625
626 ``unsigned char uuid[NVME_UUID_LEN]``
627 Binary encoded input UUID
628
629 **Return**
630
631 Returns error code if type conversion fails.
632
633
634 .. c:function:: int nvme_uuid_random (unsigned char uuid[NVME_UUID_LEN])
635
636 Generate random UUID
637
638 **Parameters**
639
640 ``unsigned char uuid[NVME_UUID_LEN]``
641 Generated random UUID
642
643 **Description**
644
645 Generate random number according
646 https://www.rfc-editor.org/rfc/rfc4122#section-4.4
647
648 **Return**
649
650 Returns error code if generating of random number fails.
651
652
653 .. c:function:: int nvme_uuid_find (struct nvme_id_uuid_list *uuid_list, const unsigned char uuid[NVME_UUID_LEN])
654
655 Find UUID position on UUID list
656
657 **Parameters**
658
659 ``struct nvme_id_uuid_list *uuid_list``
660 UUID list returned by identify UUID
661
662 ``const unsigned char uuid[NVME_UUID_LEN]``
663 Binary encoded input UUID
664
665 **Return**
666
667 The array position where given UUID is present, or -1 on failure with errno set.
668
669
670 .. c:function:: bool nvme_ipaddrs_eq (const char *addr1, const char *addr2)
671
672 Check if 2 IP addresses are equal.
673
674 **Parameters**
675
676 ``const char *addr1``
677 IP address (can be IPv4 or IPv6)
678
679 ``const char *addr2``
680 IP address (can be IPv4 or IPv6)
681
682 **Return**
683
684 true if addr1 == addr2. false otherwise.
685
686
687 .. c:function:: const char * nvme_iface_matching_addr (const struct ifaddrs *iface_list, const char *addr)
688
689 Get interface matching **addr**
690
691 **Parameters**
692
693 ``const struct ifaddrs *iface_list``
694 Interface list returned by getifaddrs()
695
696 ``const char *addr``
697 Address to match
698
699 **Description**
700
701 Parse the interface list pointed to by **iface_list** looking
702 for the interface that has **addr** as one of its assigned
703 addresses.
704
705 **Return**
706
707 The name of the interface that owns **addr** or NULL.
708
709
710 .. c:function:: bool nvme_iface_primary_addr_matches (const struct ifaddrs *iface_list, const char *iface, const char *addr)
711
712 Check that interface's primary address matches
713
714 **Parameters**
715
716 ``const struct ifaddrs *iface_list``
717 Interface list returned by getifaddrs()
718
719 ``const char *iface``
720 Interface to match
721
722 ``const char *addr``
723 Address to match
724
725 **Description**
726
727 Parse the interface list pointed to by **iface_list** and looking for
728 interface **iface**. The get its primary address and check if it matches
729 **addr**.
730
731 **Return**
732
733 true if a match is found, false otherwise.
734
735