Debian Codegraph @

doc/rst/tree.rst

raw
1 .. _tree.h:
2
3 **tree.h**
4
5
6 libnvme tree object interface
7
8 .. c:function:: nvme_root_t nvme_create_root (FILE *fp, int log_level)
9
10 Initialize root object
11
12 **Parameters**
13
14 ``FILE *fp``
15 File descriptor for logging messages
16
17 ``int log_level``
18 Logging level to use
19
20 **Return**
21
22 Initialized :c:type:`nvme_root_t` object
23
24
25 .. c:function:: void nvme_root_set_application (nvme_root_t r, const char *a)
26
27 Specify managing application
28
29 **Parameters**
30
31 ``nvme_root_t r``
32 :c:type:`nvme_root_t` object
33
34 ``const char *a``
35 Application string
36
37 **Description**
38
39 Sets the managing application string for **r**.
40
41
42 .. c:function:: const char * nvme_root_get_application (nvme_root_t r)
43
44 Get managing application
45
46 **Parameters**
47
48 ``nvme_root_t r``
49 :c:type:`nvme_root_t` object
50
51 **Description**
52
53 Returns the managing application string for **r** or NULL if not set.
54
55
56 .. c:function:: void nvme_root_skip_namespaces (nvme_root_t r)
57
58 Skip namespace scanning
59
60 **Parameters**
61
62 ``nvme_root_t r``
63 :c:type:`nvme_root_t` object
64
65 **Description**
66
67 Sets a flag to skip namespaces during scanning.
68
69
70 .. c:function:: void nvme_root_release_fds (nvme_root_t r)
71
72 Close all opened file descriptors in the tree
73
74 **Parameters**
75
76 ``nvme_root_t r``
77 :c:type:`nvme_root_t` object
78
79 **Description**
80
81 Controller and Namespace objects cache the file descriptors
82 of opened nvme devices. This API can be used to close and
83 clear all cached fds in the tree.
84
85
86 .. c:function:: void nvme_free_tree (nvme_root_t r)
87
88 Free root object
89
90 **Parameters**
91
92 ``nvme_root_t r``
93 :c:type:`nvme_root_t` object
94
95 **Description**
96
97 Free an :c:type:`nvme_root_t` object and all attached objects
98
99
100 .. c:function:: nvme_host_t nvme_first_host (nvme_root_t r)
101
102 Start host iterator
103
104 **Parameters**
105
106 ``nvme_root_t r``
107 :c:type:`nvme_root_t` object
108
109 **Return**
110
111 First :c:type:`nvme_host_t` object in an iterator
112
113
114 .. c:function:: nvme_host_t nvme_next_host (nvme_root_t r, nvme_host_t h)
115
116 Next host iterator
117
118 **Parameters**
119
120 ``nvme_root_t r``
121 :c:type:`nvme_root_t` object
122
123 ``nvme_host_t h``
124 Previous :c:type:`nvme_host_t` iterator
125
126 **Return**
127
128 Next :c:type:`nvme_host_t` object in an iterator
129
130
131 .. c:function:: nvme_root_t nvme_host_get_root (nvme_host_t h)
132
133 Returns nvme_root_t object
134
135 **Parameters**
136
137 ``nvme_host_t h``
138 :c:type:`nvme_host_t` object
139
140 **Return**
141
142 :c:type:`nvme_root_t` object from **h**
143
144
145 .. c:function:: nvme_host_t nvme_lookup_host (nvme_root_t r, const char *hostnqn, const char *hostid)
146
147 Lookup nvme_host_t object
148
149 **Parameters**
150
151 ``nvme_root_t r``
152 :c:type:`nvme_root_t` object
153
154 ``const char *hostnqn``
155 Host NQN
156
157 ``const char *hostid``
158 Host ID
159
160 **Description**
161
162 Lookup a nvme_host_t object based on **hostnqn** and **hostid**
163 or create one if not found.
164
165 **Return**
166
167 :c:type:`nvme_host_t` object
168
169
170 .. c:function:: const char * nvme_host_get_dhchap_key (nvme_host_t h)
171
172 Return host key
173
174 **Parameters**
175
176 ``nvme_host_t h``
177 Host for which the key should be returned
178
179 **Return**
180
181 DH-HMAC-CHAP host key or NULL if not set
182
183
184 .. c:function:: void nvme_host_set_dhchap_key (nvme_host_t h, const char *key)
185
186 set host key
187
188 **Parameters**
189
190 ``nvme_host_t h``
191 Host for which the key should be set
192
193 ``const char *key``
194 DH-HMAC-CHAP Key to set or NULL to clear existing key
195
196
197 .. c:function:: void nvme_host_set_pdc_enabled (nvme_host_t h, bool enabled)
198
199 Set Persistent Discovery Controller flag
200
201 **Parameters**
202
203 ``nvme_host_t h``
204 Host for which the falg should be set
205
206 ``bool enabled``
207 The bool to set the enabled flag
208
209 **Description**
210
211 When nvme_host_set_pdc_enabled() is not used to set the PDC flag,
212 nvme_host_is_pdc_enabled() will return the default value which was
213 passed into the function and not the undefined flag value.
214
215
216 .. c:function:: bool nvme_host_is_pdc_enabled (nvme_host_t h, bool fallback)
217
218 Is Persistenct Discovery Controller enabled
219
220 **Parameters**
221
222 ``nvme_host_t h``
223 Host which to check if PDC is enabled
224
225 ``bool fallback``
226 The fallback default value of the flag when
227 **nvme_host_set_pdc_enabled** has not be used
228 to set the flag.
229
230 **Return**
231
232 true if PDC is enabled for **h**, else false
233
234
235 .. c:function:: nvme_host_t nvme_default_host (nvme_root_t r)
236
237 Initializes the default host
238
239 **Parameters**
240
241 ``nvme_root_t r``
242 :c:type:`nvme_root_t` object
243
244 **Description**
245
246 Initializes the default host object based on the hostnqn/hostid
247 values returned by nvme_host_get_ids() and attaches it to **r**.
248
249 **Return**
250
251 :c:type:`nvme_host_t` object
252
253
254 .. c:function:: int nvme_host_get_ids (nvme_root_t r, char *hostnqn_arg, char *hostid_arg, char **hostnqn, char **hostid)
255
256 Retrieve host ids from various sources
257
258 **Parameters**
259
260 ``nvme_root_t r``
261 :c:type:`nvme_root_t` object
262
263 ``char *hostnqn_arg``
264 Input hostnqn (command line) argument
265
266 ``char *hostid_arg``
267 Input hostid (command line) argument
268
269 ``char **hostnqn``
270 Output hostnqn
271
272 ``char **hostid``
273 Output hostid
274
275 **Description**
276
277 nvme_host_get_ids figures out which hostnqn/hostid is to be used.
278 There are several sources where this information can be retrieved.
279
280 The order is:
281
282 - Start with informartion from DMI or device-tree
283 - Override hostnqn and hostid from /etc/nvme files
284 - Override hostnqn or hostid with values from JSON
285 configuration file. The first host entry in the file is
286 considered the default host.
287 - Override hostnqn or hostid with values from the command line
288 (**hostnqn_arg**, **hostid_arg**).
289
290 If the IDs are still NULL after the lookup algorithm, the function
291 will generate random IDs.
292
293 The function also verifies that hostnqn and hostid matches. The Linux
294 NVMe implementation expects a 1:1 matching between the IDs.
295
296 **Return**
297
298 0 on success (**hostnqn** and **hostid** contain valid strings
299 which the caller needs to free), -1 otherwise and errno is set.
300
301
302 .. c:function:: nvme_subsystem_t nvme_first_subsystem (nvme_host_t h)
303
304 Start subsystem iterator
305
306 **Parameters**
307
308 ``nvme_host_t h``
309 :c:type:`nvme_host_t` object
310
311 **Return**
312
313 first :c:type:`nvme_subsystem_t` object in an iterator
314
315
316 .. c:function:: nvme_subsystem_t nvme_next_subsystem (nvme_host_t h, nvme_subsystem_t s)
317
318 Next subsystem iterator
319
320 **Parameters**
321
322 ``nvme_host_t h``
323 :c:type:`nvme_host_t` object
324
325 ``nvme_subsystem_t s``
326 Previous :c:type:`nvme_subsystem_t` iterator
327
328 **Return**
329
330 next :c:type:`nvme_subsystem_t` object in an iterator
331
332
333 .. c:function:: nvme_subsystem_t nvme_lookup_subsystem (struct nvme_host *h, const char *name, const char *subsysnqn)
334
335 Lookup nvme_subsystem_t object
336
337 **Parameters**
338
339 ``struct nvme_host *h``
340 :c:type:`nvme_host_t` object
341
342 ``const char *name``
343 Name of the subsystem (may be NULL)
344
345 ``const char *subsysnqn``
346 Subsystem NQN
347
348 **Description**
349
350 Lookup a :c:type:`nvme_subsystem_t` object in **h** base on **name** (if present)
351 and **subsysnqn** or create one if not found.
352
353 **Return**
354
355 nvme_subsystem_t object
356
357
358 .. c:function:: void nvme_free_subsystem (struct nvme_subsystem *s)
359
360 Free a subsystem
361
362 **Parameters**
363
364 ``struct nvme_subsystem *s``
365 subsystem
366
367 **Description**
368
369 Frees **s** and all related objects.
370
371
372 .. c:function:: nvme_host_t nvme_subsystem_get_host (nvme_subsystem_t s)
373
374 Returns nvme_host_t object
375
376 **Parameters**
377
378 ``nvme_subsystem_t s``
379 subsystem
380
381 **Return**
382
383 :c:type:`nvme_host_t` object from **s**
384
385
386 .. c:function:: nvme_ns_t nvme_ctrl_first_ns (nvme_ctrl_t c)
387
388 Start namespace iterator
389
390 **Parameters**
391
392 ``nvme_ctrl_t c``
393 Controller instance
394
395 **Return**
396
397 First :c:type:`nvme_ns_t` object of an **c** iterator
398
399
400 .. c:function:: nvme_ns_t nvme_ctrl_next_ns (nvme_ctrl_t c, nvme_ns_t n)
401
402 Next namespace iterator
403
404 **Parameters**
405
406 ``nvme_ctrl_t c``
407 Controller instance
408
409 ``nvme_ns_t n``
410 Previous nvme_ns_t iterator
411
412 **Return**
413
414 Next nvme_ns_t object of an **c** iterator
415
416
417 .. c:function:: nvme_path_t nvme_ctrl_first_path (nvme_ctrl_t c)
418
419 Start path iterator
420
421 **Parameters**
422
423 ``nvme_ctrl_t c``
424 Controller instance
425
426 **Return**
427
428 First :c:type:`nvme_path_t` object of an **c** iterator
429
430
431 .. c:function:: nvme_path_t nvme_ctrl_next_path (nvme_ctrl_t c, nvme_path_t p)
432
433 Next path iterator
434
435 **Parameters**
436
437 ``nvme_ctrl_t c``
438 Controller instance
439
440 ``nvme_path_t p``
441 Previous :c:type:`nvme_path_t` object of an **c** iterator
442
443 **Return**
444
445 Next :c:type:`nvme_path_t` object of an **c** iterator
446
447
448 .. c:function:: nvme_ctrl_t nvme_subsystem_first_ctrl (nvme_subsystem_t s)
449
450 First ctrl iterator
451
452 **Parameters**
453
454 ``nvme_subsystem_t s``
455 :c:type:`nvme_subsystem_t` object
456
457 **Return**
458
459 First controller of an **s** iterator
460
461
462 .. c:function:: nvme_ctrl_t nvme_subsystem_next_ctrl (nvme_subsystem_t s, nvme_ctrl_t c)
463
464 Next ctrl iterator
465
466 **Parameters**
467
468 ``nvme_subsystem_t s``
469 :c:type:`nvme_subsystem_t` object
470
471 ``nvme_ctrl_t c``
472 Previous controller instance of an **s** iterator
473
474 **Return**
475
476 Next controller of an **s** iterator
477
478
479 .. c:function:: nvme_path_t nvme_namespace_first_path (nvme_ns_t ns)
480
481 Start path iterator
482
483 **Parameters**
484
485 ``nvme_ns_t ns``
486 Namespace instance
487
488 **Return**
489
490 First :c:type:`nvme_path_t` object of an **ns** iterator
491
492
493 .. c:function:: nvme_path_t nvme_namespace_next_path (nvme_ns_t ns, nvme_path_t p)
494
495 Next path iterator
496
497 **Parameters**
498
499 ``nvme_ns_t ns``
500 Namespace instance
501
502 ``nvme_path_t p``
503 Previous :c:type:`nvme_path_t` object of an **ns** iterator
504
505 **Return**
506
507 Next :c:type:`nvme_path_t` object of an **ns** iterator
508
509
510 .. c:function:: nvme_ctrl_t nvme_lookup_ctrl (nvme_subsystem_t s, const char *transport, const char *traddr, const char *host_traddr, const char *host_iface, const char *trsvcid, nvme_ctrl_t p)
511
512 Lookup nvme_ctrl_t object
513
514 **Parameters**
515
516 ``nvme_subsystem_t s``
517 :c:type:`nvme_subsystem_t` object
518
519 ``const char *transport``
520 Transport name
521
522 ``const char *traddr``
523 Transport address
524
525 ``const char *host_traddr``
526 Host transport address
527
528 ``const char *host_iface``
529 Host interface name
530
531 ``const char *trsvcid``
532 Transport service identifier
533
534 ``nvme_ctrl_t p``
535 Previous controller instance
536
537 **Description**
538
539 Lookup a controller in **s** based on **transport**, **traddr**,
540 **host_traddr**, **host_iface**, and **trsvcid**. **transport** must be specified,
541 other fields may be required depending on the transport. A new
542 object is created if none is found. If **p** is specified the lookup
543 will start at **p** instead of the first controller.
544
545 **Return**
546
547 Controller instance
548
549
550 .. c:function:: nvme_ctrl_t nvme_ctrl_find (nvme_subsystem_t s, const char *transport, const char *traddr, const char *trsvcid, const char *subsysnqn, const char *host_traddr, const char *host_iface)
551
552 Locate an existing controller
553
554 **Parameters**
555
556 ``nvme_subsystem_t s``
557 :c:type:`nvme_subsystem_t` object
558
559 ``const char *transport``
560 Transport name
561
562 ``const char *traddr``
563 Transport address
564
565 ``const char *trsvcid``
566 Transport service identifier
567
568 ``const char *subsysnqn``
569 Subsystem NQN
570
571 ``const char *host_traddr``
572 Host transport address
573
574 ``const char *host_iface``
575 Host interface name
576
577 **Description**
578
579 Lookup a controller in **s** based on **transport**, **traddr**, **trsvcid**,
580 **subsysnqn**, **host_traddr**, and **host_iface**. **transport** must be specified,
581 other fields may be required depending on the transport. Parameters set
582 to NULL will be ignored.
583
584 Unlike nvme_lookup_ctrl(), this function does not create a new object if
585 an existing controller cannot be found.
586
587 **Return**
588
589 Controller instance on success, NULL otherwise.
590
591
592 .. c:function:: bool nvme_ctrl_config_match (struct nvme_ctrl *c, const char *transport, const char *traddr, const char *trsvcid, const char *subsysnqn, const char *host_traddr, const char *host_iface)
593
594 Check if ctrl **c** matches config params
595
596 **Parameters**
597
598 ``struct nvme_ctrl *c``
599 An existing controller instance
600
601 ``const char *transport``
602 Transport name
603
604 ``const char *traddr``
605 Transport address
606
607 ``const char *trsvcid``
608 Transport service identifier
609
610 ``const char *subsysnqn``
611 Subsystem NQN
612
613 ``const char *host_traddr``
614 Host transport address
615
616 ``const char *host_iface``
617 Host interface name
618
619 **Description**
620
621 Check that controller **c** matches parameters: **transport**, **traddr**,
622 **trsvcid**, **subsysnqn**, **host_traddr**, and **host_iface**. Parameters set
623 to NULL will be ignored.
624
625 **Return**
626
627 true if there's a match, false otherwise.
628
629
630 .. c:function:: nvme_ctrl_t nvme_create_ctrl (nvme_root_t r, const char *subsysnqn, const char *transport, const char *traddr, const char *host_traddr, const char *host_iface, const char *trsvcid)
631
632 Allocate an unconnected NVMe controller
633
634 **Parameters**
635
636 ``nvme_root_t r``
637 NVMe root element
638
639 ``const char *subsysnqn``
640 Subsystem NQN
641
642 ``const char *transport``
643 Transport type
644
645 ``const char *traddr``
646 Transport address
647
648 ``const char *host_traddr``
649 Host transport address
650
651 ``const char *host_iface``
652 Host interface name
653
654 ``const char *trsvcid``
655 Transport service ID
656
657 **Description**
658
659 Creates an unconnected controller to be used for nvme_add_ctrl().
660
661 **Return**
662
663 Controller instance
664
665
666 .. c:function:: nvme_ns_t nvme_subsystem_first_ns (nvme_subsystem_t s)
667
668 Start namespace iterator
669
670 **Parameters**
671
672 ``nvme_subsystem_t s``
673 :c:type:`nvme_subsystem_t` object
674
675 **Return**
676
677 First :c:type:`nvme_ns_t` object of an **s** iterator
678
679
680 .. c:function:: nvme_ns_t nvme_subsystem_next_ns (nvme_subsystem_t s, nvme_ns_t n)
681
682 Next namespace iterator
683
684 **Parameters**
685
686 ``nvme_subsystem_t s``
687 :c:type:`nvme_subsystem_t` object
688
689 ``nvme_ns_t n``
690 Previous :c:type:`nvme_ns_t` iterator
691
692 **Return**
693
694 Next :c:type:`nvme_ns_t` object of an **s** iterator
695
696
697 .. c:function:: nvme_for_each_host_safe (r, h, _h)
698
699 Traverse host list
700
701 **Parameters**
702
703 ``r``
704 :c:type:`nvme_root_t` object
705
706 ``h``
707 :c:type:`nvme_host_t` object
708
709 ``_h``
710 Temporary :c:type:`nvme_host_t` object
711
712
713 .. c:function:: nvme_for_each_host (r, h)
714
715 Traverse host list
716
717 **Parameters**
718
719 ``r``
720 :c:type:`nvme_root_t` object
721
722 ``h``
723 :c:type:`nvme_host_t` object
724
725
726 .. c:function:: nvme_for_each_subsystem_safe (h, s, _s)
727
728 Traverse subsystems
729
730 **Parameters**
731
732 ``h``
733 :c:type:`nvme_host_t` object
734
735 ``s``
736 :c:type:`nvme_subsystem_t` object
737
738 ``_s``
739 Temporary :c:type:`nvme_subsystem_t` object
740
741
742 .. c:function:: nvme_for_each_subsystem (h, s)
743
744 Traverse subsystems
745
746 **Parameters**
747
748 ``h``
749 :c:type:`nvme_host_t` object
750
751 ``s``
752 :c:type:`nvme_subsystem_t` object
753
754
755 .. c:function:: nvme_subsystem_for_each_ctrl_safe (s, c, _c)
756
757 Traverse controllers
758
759 **Parameters**
760
761 ``s``
762 :c:type:`nvme_subsystem_t` object
763
764 ``c``
765 Controller instance
766
767 ``_c``
768 A :c:type:`nvme_ctrl_t_node` to use as temporary storage
769
770
771 .. c:function:: nvme_subsystem_for_each_ctrl (s, c)
772
773 Traverse controllers
774
775 **Parameters**
776
777 ``s``
778 :c:type:`nvme_subsystem_t` object
779
780 ``c``
781 Controller instance
782
783
784 .. c:function:: nvme_ctrl_for_each_ns_safe (c, n, _n)
785
786 Traverse namespaces
787
788 **Parameters**
789
790 ``c``
791 Controller instance
792
793 ``n``
794 :c:type:`nvme_ns_t` object
795
796 ``_n``
797 A :c:type:`nvme_ns_t_node` to use as temporary storage
798
799
800 .. c:function:: nvme_ctrl_for_each_ns (c, n)
801
802 Traverse namespaces
803
804 **Parameters**
805
806 ``c``
807 Controller instance
808
809 ``n``
810 :c:type:`nvme_ns_t` object
811
812
813 .. c:function:: nvme_ctrl_for_each_path_safe (c, p, _p)
814
815 Traverse paths
816
817 **Parameters**
818
819 ``c``
820 Controller instance
821
822 ``p``
823 :c:type:`nvme_path_t` object
824
825 ``_p``
826 A :c:type:`nvme_path_t_node` to use as temporary storage
827
828
829 .. c:function:: nvme_ctrl_for_each_path (c, p)
830
831 Traverse paths
832
833 **Parameters**
834
835 ``c``
836 Controller instance
837
838 ``p``
839 :c:type:`nvme_path_t` object
840
841
842 .. c:function:: nvme_subsystem_for_each_ns_safe (s, n, _n)
843
844 Traverse namespaces
845
846 **Parameters**
847
848 ``s``
849 :c:type:`nvme_subsystem_t` object
850
851 ``n``
852 :c:type:`nvme_ns_t` object
853
854 ``_n``
855 A :c:type:`nvme_ns_t_node` to use as temporary storage
856
857
858 .. c:function:: nvme_subsystem_for_each_ns (s, n)
859
860 Traverse namespaces
861
862 **Parameters**
863
864 ``s``
865 :c:type:`nvme_subsystem_t` object
866
867 ``n``
868 :c:type:`nvme_ns_t` object
869
870
871 .. c:function:: nvme_namespace_for_each_path_safe (n, p, _p)
872
873 Traverse paths
874
875 **Parameters**
876
877 ``n``
878 Namespace instance
879
880 ``p``
881 :c:type:`nvme_path_t` object
882
883 ``_p``
884 A :c:type:`nvme_path_t_node` to use as temporary storage
885
886
887 .. c:function:: nvme_namespace_for_each_path (n, p)
888
889 Traverse paths
890
891 **Parameters**
892
893 ``n``
894 Namespace instance
895
896 ``p``
897 :c:type:`nvme_path_t` object
898
899
900 .. c:function:: int nvme_ns_get_fd (nvme_ns_t n)
901
902 Get associated file descriptor
903
904 **Parameters**
905
906 ``nvme_ns_t n``
907 Namespace instance
908
909 **Description**
910
911 libnvme will open() the file (if not already opened) and keep
912 an internal copy of the file descriptor. Following calls to
913 this API retrieve the internal cached copy of the file
914 descriptor. The file will remain opened and the fd will
915 remain cached until the ns object is deleted or
916 nvme_ns_release_fd() is called.
917
918 **Return**
919
920 File descriptor associated with **n** or -1
921
922
923 .. c:function:: void nvme_ns_release_fd (nvme_ns_t n)
924
925 Close fd and clear fd from ns object
926
927 **Parameters**
928
929 ``nvme_ns_t n``
930 Namespace instance
931
932
933 .. c:function:: int nvme_ns_get_nsid (nvme_ns_t n)
934
935 NSID of a namespace
936
937 **Parameters**
938
939 ``nvme_ns_t n``
940 Namespace instance
941
942 **Return**
943
944 NSID of **n**
945
946
947 .. c:function:: int nvme_ns_get_lba_size (nvme_ns_t n)
948
949 LBA size of a namespace
950
951 **Parameters**
952
953 ``nvme_ns_t n``
954 Namespace instance
955
956 **Return**
957
958 LBA size of **n**
959
960
961 .. c:function:: int nvme_ns_get_meta_size (nvme_ns_t n)
962
963 Metadata size of a namespace
964
965 **Parameters**
966
967 ``nvme_ns_t n``
968 Namespace instance
969
970 **Return**
971
972 Metadata size of **n**
973
974
975 .. c:function:: uint64_t nvme_ns_get_lba_count (nvme_ns_t n)
976
977 LBA count of a namespace
978
979 **Parameters**
980
981 ``nvme_ns_t n``
982 Namespace instance
983
984 **Return**
985
986 LBA count of **n**
987
988
989 .. c:function:: uint64_t nvme_ns_get_lba_util (nvme_ns_t n)
990
991 LBA utilization of a namespace
992
993 **Parameters**
994
995 ``nvme_ns_t n``
996 Namespace instance
997
998 **Return**
999
1000 LBA utilization of **n**
1001
1002
1003 .. c:function:: enum nvme_csi nvme_ns_get_csi (nvme_ns_t n)
1004
1005 Command set identifier of a namespace
1006
1007 **Parameters**
1008
1009 ``nvme_ns_t n``
1010 Namespace instance
1011
1012 **Return**
1013
1014 The namespace's command set identifier in use
1015
1016
1017 .. c:function:: const uint8_t * nvme_ns_get_eui64 (nvme_ns_t n)
1018
1019 64-bit eui of a namespace
1020
1021 **Parameters**
1022
1023 ``nvme_ns_t n``
1024 Namespace instance
1025
1026 **Return**
1027
1028 A pointer to the 64-bit eui
1029
1030
1031 .. c:function:: const uint8_t * nvme_ns_get_nguid (nvme_ns_t n)
1032
1033 128-bit nguid of a namespace
1034
1035 **Parameters**
1036
1037 ``nvme_ns_t n``
1038 Namespace instance
1039
1040 **Return**
1041
1042 A pointer to the 128-bit nguid
1043
1044
1045 .. c:function:: void nvme_ns_get_uuid (nvme_ns_t n, unsigned char out[NVME_UUID_LEN])
1046
1047 UUID of a namespace
1048
1049 **Parameters**
1050
1051 ``nvme_ns_t n``
1052 Namespace instance
1053
1054 ``unsigned char out[NVME_UUID_LEN]``
1055 buffer for the UUID
1056
1057 **Description**
1058
1059 Copies the namespace's uuid into **out**
1060
1061
1062 .. c:function:: const char * nvme_ns_get_sysfs_dir (nvme_ns_t n)
1063
1064 sysfs directory of a namespace
1065
1066 **Parameters**
1067
1068 ``nvme_ns_t n``
1069 Namespace instance
1070
1071 **Return**
1072
1073 sysfs directory name of **n**
1074
1075
1076 .. c:function:: const char * nvme_ns_get_name (nvme_ns_t n)
1077
1078 sysfs name of a namespace
1079
1080 **Parameters**
1081
1082 ``nvme_ns_t n``
1083 Namespace instance
1084
1085 **Return**
1086
1087 sysfs name of **n**
1088
1089
1090 .. c:function:: const char * nvme_ns_get_generic_name (nvme_ns_t n)
1091
1092 Returns name of generic namespace chardev.
1093
1094 **Parameters**
1095
1096 ``nvme_ns_t n``
1097 Namespace instance
1098
1099 **Return**
1100
1101 Name of generic namespace chardev
1102
1103
1104 .. c:function:: const char * nvme_ns_get_firmware (nvme_ns_t n)
1105
1106 Firmware string of a namespace
1107
1108 **Parameters**
1109
1110 ``nvme_ns_t n``
1111 Namespace instance
1112
1113 **Return**
1114
1115 Firmware string of **n**
1116
1117
1118 .. c:function:: const char * nvme_ns_get_serial (nvme_ns_t n)
1119
1120 Serial number of a namespace
1121
1122 **Parameters**
1123
1124 ``nvme_ns_t n``
1125 Namespace instance
1126
1127 **Return**
1128
1129 Serial number string of **n**
1130
1131
1132 .. c:function:: const char * nvme_ns_get_model (nvme_ns_t n)
1133
1134 Model of a namespace
1135
1136 **Parameters**
1137
1138 ``nvme_ns_t n``
1139 Namespace instance
1140
1141 **Return**
1142
1143 Model string of **n**
1144
1145
1146 .. c:function:: nvme_subsystem_t nvme_ns_get_subsystem (nvme_ns_t n)
1147
1148 :c:type:`nvme_subsystem_t` of a namespace
1149
1150 **Parameters**
1151
1152 ``nvme_ns_t n``
1153 Namespace instance
1154
1155 **Return**
1156
1157 nvme_subsystem_t object of **n**
1158
1159
1160 .. c:function:: nvme_ctrl_t nvme_ns_get_ctrl (nvme_ns_t n)
1161
1162 :c:type:`nvme_ctrl_t` of a namespace
1163
1164 **Parameters**
1165
1166 ``nvme_ns_t n``
1167 Namespace instance
1168
1169 **Description**
1170
1171 nvme_ctrl_t object may be NULL for a multipathed namespace
1172
1173 **Return**
1174
1175 nvme_ctrl_t object of **n** if present
1176
1177
1178 .. c:function:: void nvme_free_ns (struct nvme_ns *n)
1179
1180 Free a namespace object
1181
1182 **Parameters**
1183
1184 ``struct nvme_ns *n``
1185 Namespace instance
1186
1187
1188 .. c:function:: int nvme_ns_read (nvme_ns_t n, void *buf, off_t offset, size_t count)
1189
1190 Read from a namespace
1191
1192 **Parameters**
1193
1194 ``nvme_ns_t n``
1195 Namespace instance
1196
1197 ``void *buf``
1198 Buffer into which the data will be transferred
1199
1200 ``off_t offset``
1201 LBA offset of **n**
1202
1203 ``size_t count``
1204 Number of sectors in **buf**
1205
1206 **Return**
1207
1208 Number of sectors read or -1 on error.
1209
1210
1211 .. c:function:: int nvme_ns_write (nvme_ns_t n, void *buf, off_t offset, size_t count)
1212
1213 Write to a namespace
1214
1215 **Parameters**
1216
1217 ``nvme_ns_t n``
1218 Namespace instance
1219
1220 ``void *buf``
1221 Buffer with data to be written
1222
1223 ``off_t offset``
1224 LBA offset of **n**
1225
1226 ``size_t count``
1227 Number of sectors in **buf**
1228
1229 **Return**
1230
1231 Number of sectors written or -1 on error
1232
1233
1234 .. c:function:: int nvme_ns_verify (nvme_ns_t n, off_t offset, size_t count)
1235
1236 Verify data on a namespace
1237
1238 **Parameters**
1239
1240 ``nvme_ns_t n``
1241 Namespace instance
1242
1243 ``off_t offset``
1244 LBA offset of **n**
1245
1246 ``size_t count``
1247 Number of sectors to be verified
1248
1249 **Return**
1250
1251 Number of sectors verified
1252
1253
1254 .. c:function:: int nvme_ns_compare (nvme_ns_t n, void *buf, off_t offset, size_t count)
1255
1256 Compare data on a namespace
1257
1258 **Parameters**
1259
1260 ``nvme_ns_t n``
1261 Namespace instance
1262
1263 ``void *buf``
1264 Buffer with data to be compared
1265
1266 ``off_t offset``
1267 LBA offset of **n**
1268
1269 ``size_t count``
1270 Number of sectors in **buf**
1271
1272 **Return**
1273
1274 Number of sectors compared
1275
1276
1277 .. c:function:: int nvme_ns_write_zeros (nvme_ns_t n, off_t offset, size_t count)
1278
1279 Write zeros to a namespace
1280
1281 **Parameters**
1282
1283 ``nvme_ns_t n``
1284 Namespace instance
1285
1286 ``off_t offset``
1287 LBA offset in **n**
1288
1289 ``size_t count``
1290 Number of sectors to be written
1291
1292 **Return**
1293
1294 Number of sectors written
1295
1296
1297 .. c:function:: int nvme_ns_write_uncorrectable (nvme_ns_t n, off_t offset, size_t count)
1298
1299 Issus a 'write uncorrectable' command
1300
1301 **Parameters**
1302
1303 ``nvme_ns_t n``
1304 Namespace instance
1305
1306 ``off_t offset``
1307 LBA offset in **n**
1308
1309 ``size_t count``
1310 Number of sectors to be written
1311
1312 **Return**
1313
1314 Number of sectors written
1315
1316
1317 .. c:function:: int nvme_ns_flush (nvme_ns_t n)
1318
1319 Flush data to a namespace
1320
1321 **Parameters**
1322
1323 ``nvme_ns_t n``
1324 Namespace instance
1325
1326 **Return**
1327
1328 0 on success, -1 on error.
1329
1330
1331 .. c:function:: int nvme_ns_identify (nvme_ns_t n, struct nvme_id_ns *ns)
1332
1333 Issue an 'identify namespace' command
1334
1335 **Parameters**
1336
1337 ``nvme_ns_t n``
1338 Namespace instance
1339
1340 ``struct nvme_id_ns *ns``
1341 :c:type:`nvme_id_ns` buffer
1342
1343 **Description**
1344
1345 Writes the data returned by the 'identify namespace' command
1346 into **ns**.
1347
1348 **Return**
1349
1350 0 on success, -1 on error.
1351
1352
1353 .. c:function:: int nvme_ns_identify_descs (nvme_ns_t n, struct nvme_ns_id_desc *descs)
1354
1355 Issue an 'identify descriptors' command
1356
1357 **Parameters**
1358
1359 ``nvme_ns_t n``
1360 Namespace instance
1361
1362 ``struct nvme_ns_id_desc *descs``
1363 List of identify descriptors
1364
1365 **Description**
1366
1367 Writes the data returned by the 'identify descriptors' command
1368 into **descs**.
1369
1370 **Return**
1371
1372 0 on success, -1 on error.
1373
1374
1375 .. c:function:: const char * nvme_path_get_name (nvme_path_t p)
1376
1377 sysfs name of an :c:type:`nvme_path_t` object
1378
1379 **Parameters**
1380
1381 ``nvme_path_t p``
1382 :c:type:`nvme_path_t` object
1383
1384 **Return**
1385
1386 sysfs name of **p**
1387
1388
1389 .. c:function:: const char * nvme_path_get_sysfs_dir (nvme_path_t p)
1390
1391 sysfs directory of an nvme_path_t object
1392
1393 **Parameters**
1394
1395 ``nvme_path_t p``
1396 :c:type:`nvme_path_t` object
1397
1398 **Return**
1399
1400 sysfs directory of **p**
1401
1402
1403 .. c:function:: const char * nvme_path_get_ana_state (nvme_path_t p)
1404
1405 ANA state of an nvme_path_t object
1406
1407 **Parameters**
1408
1409 ``nvme_path_t p``
1410 :c:type:`nvme_path_t` object
1411
1412 **Return**
1413
1414 ANA (Asynchronous Namespace Access) state of **p**
1415
1416
1417 .. c:function:: const char * nvme_path_get_numa_nodes (nvme_path_t p)
1418
1419 NUMA nodes of an nvme_path_t object
1420
1421 **Parameters**
1422
1423 ``nvme_path_t p``
1424 :c:type:`nvme_path_t` object
1425
1426 **Return**
1427
1428 NUMA nodes associated to **p**
1429
1430
1431 .. c:function:: int nvme_path_get_queue_depth (nvme_path_t p)
1432
1433 Queue depth of an nvme_path_t object
1434
1435 **Parameters**
1436
1437 ``nvme_path_t p``
1438 :c:type:`nvme_path_t` object
1439
1440 **Return**
1441
1442 Queue depth of **p**
1443
1444
1445 .. c:function:: nvme_ctrl_t nvme_path_get_ctrl (nvme_path_t p)
1446
1447 Parent controller of an nvme_path_t object
1448
1449 **Parameters**
1450
1451 ``nvme_path_t p``
1452 :c:type:`nvme_path_t` object
1453
1454 **Return**
1455
1456 Parent controller if present
1457
1458
1459 .. c:function:: nvme_ns_t nvme_path_get_ns (nvme_path_t p)
1460
1461 Parent namespace of an nvme_path_t object
1462
1463 **Parameters**
1464
1465 ``nvme_path_t p``
1466 :c:type:`nvme_path_t` object
1467
1468 **Return**
1469
1470 Parent namespace if present
1471
1472
1473 .. c:function:: int nvme_ctrl_get_fd (nvme_ctrl_t c)
1474
1475 Get associated file descriptor
1476
1477 **Parameters**
1478
1479 ``nvme_ctrl_t c``
1480 Controller instance
1481
1482 **Description**
1483
1484 libnvme will open() the file (if not already opened) and keep
1485 an internal copy of the file descriptor. Following calls to
1486 this API retrieve the internal cached copy of the file
1487 descriptor. The file will remain opened and the fd will
1488 remain cached until the controller object is deleted or
1489 nvme_ctrl_release_fd() is called.
1490
1491 **Return**
1492
1493 File descriptor associated with **c** or -1
1494
1495
1496 .. c:function:: void nvme_ctrl_release_fd (nvme_ctrl_t c)
1497
1498 Close fd and clear fd from controller object
1499
1500 **Parameters**
1501
1502 ``nvme_ctrl_t c``
1503 Controller instance
1504
1505
1506 .. c:function:: const char * nvme_ctrl_get_name (nvme_ctrl_t c)
1507
1508 sysfs name of a controller
1509
1510 **Parameters**
1511
1512 ``nvme_ctrl_t c``
1513 Controller instance
1514
1515 **Return**
1516
1517 sysfs name of **c**
1518
1519
1520 .. c:function:: const char * nvme_ctrl_get_sysfs_dir (nvme_ctrl_t c)
1521
1522 sysfs directory of a controller
1523
1524 **Parameters**
1525
1526 ``nvme_ctrl_t c``
1527 Controller instance
1528
1529 **Return**
1530
1531 sysfs directory name of **c**
1532
1533
1534 .. c:function:: const char * nvme_ctrl_get_address (nvme_ctrl_t c)
1535
1536 Address string of a controller
1537
1538 **Parameters**
1539
1540 ``nvme_ctrl_t c``
1541 Controller instance
1542
1543 **Return**
1544
1545 NVMe-over-Fabrics address string of **c** or empty string
1546 of no address is present.
1547
1548
1549 .. c:function:: char * nvme_ctrl_get_src_addr (nvme_ctrl_t c, char *src_addr, size_t src_addr_len)
1550
1551 Extract src_addr from the c->address string
1552
1553 **Parameters**
1554
1555 ``nvme_ctrl_t c``
1556 Controller instance
1557
1558 ``char *src_addr``
1559 Where to copy the src_addr. Size must be at least INET6_ADDRSTRLEN.
1560
1561 ``size_t src_addr_len``
1562 Length of the buffer **src_addr**.
1563
1564 **Return**
1565
1566 Pointer to **src_addr** on success. NULL on failure to extract the src_addr.
1567
1568
1569 .. c:function:: const char * nvme_ctrl_get_phy_slot (nvme_ctrl_t c)
1570
1571 PCI physical slot number of a controller
1572
1573 **Parameters**
1574
1575 ``nvme_ctrl_t c``
1576 Controller instance
1577
1578 **Return**
1579
1580 PCI physical slot number of **c** or empty string if slot
1581 number is not present.
1582
1583
1584 .. c:function:: const char * nvme_ctrl_get_firmware (nvme_ctrl_t c)
1585
1586 Firmware string of a controller
1587
1588 **Parameters**
1589
1590 ``nvme_ctrl_t c``
1591 Controller instance
1592
1593 **Return**
1594
1595 Firmware string of **c**
1596
1597
1598 .. c:function:: const char * nvme_ctrl_get_model (nvme_ctrl_t c)
1599
1600 Model of a controller
1601
1602 **Parameters**
1603
1604 ``nvme_ctrl_t c``
1605 Controller instance
1606
1607 **Return**
1608
1609 Model string of **c**
1610
1611
1612 .. c:function:: const char * nvme_ctrl_get_state (nvme_ctrl_t c)
1613
1614 Running state of a controller
1615
1616 **Parameters**
1617
1618 ``nvme_ctrl_t c``
1619 Controller instance
1620
1621 **Return**
1622
1623 String indicating the running state of **c**
1624
1625
1626 .. c:function:: const char * nvme_ctrl_get_numa_node (nvme_ctrl_t c)
1627
1628 NUMA node of a controller
1629
1630 **Parameters**
1631
1632 ``nvme_ctrl_t c``
1633 Controller instance
1634
1635 **Return**
1636
1637 String indicating the NUMA node
1638
1639
1640 .. c:function:: const char * nvme_ctrl_get_queue_count (nvme_ctrl_t c)
1641
1642 Queue count of a controller
1643
1644 **Parameters**
1645
1646 ``nvme_ctrl_t c``
1647 Controller instance
1648
1649 **Return**
1650
1651 Queue count of **c**
1652
1653
1654 .. c:function:: const char * nvme_ctrl_get_serial (nvme_ctrl_t c)
1655
1656 Serial number of a controller
1657
1658 **Parameters**
1659
1660 ``nvme_ctrl_t c``
1661 Controller instance
1662
1663 **Return**
1664
1665 Serial number string of **c**
1666
1667
1668 .. c:function:: const char * nvme_ctrl_get_sqsize (nvme_ctrl_t c)
1669
1670 SQ size of a controller
1671
1672 **Parameters**
1673
1674 ``nvme_ctrl_t c``
1675 Controller instance
1676
1677 **Return**
1678
1679 SQ size (as string) of **c**
1680
1681
1682 .. c:function:: const char * nvme_ctrl_get_transport (nvme_ctrl_t c)
1683
1684 Transport type of a controller
1685
1686 **Parameters**
1687
1688 ``nvme_ctrl_t c``
1689 Controller instance
1690
1691 **Return**
1692
1693 Transport type of **c**
1694
1695
1696 .. c:function:: const char * nvme_ctrl_get_subsysnqn (nvme_ctrl_t c)
1697
1698 Subsystem NQN of a controller
1699
1700 **Parameters**
1701
1702 ``nvme_ctrl_t c``
1703 Controller instance
1704
1705 **Return**
1706
1707 Subsystem NQN of **c**
1708
1709
1710 .. c:function:: nvme_subsystem_t nvme_ctrl_get_subsystem (nvme_ctrl_t c)
1711
1712 Parent subsystem of a controller
1713
1714 **Parameters**
1715
1716 ``nvme_ctrl_t c``
1717 Controller instance
1718
1719 **Return**
1720
1721 Parent nvme_subsystem_t object
1722
1723
1724 .. c:function:: const char * nvme_ctrl_get_traddr (nvme_ctrl_t c)
1725
1726 Transport address of a controller
1727
1728 **Parameters**
1729
1730 ``nvme_ctrl_t c``
1731 Controller instance
1732
1733 **Return**
1734
1735 Transport address of **c**
1736
1737
1738 .. c:function:: const char * nvme_ctrl_get_trsvcid (nvme_ctrl_t c)
1739
1740 Transport service identifier of a controller
1741
1742 **Parameters**
1743
1744 ``nvme_ctrl_t c``
1745 Controller instance
1746
1747 **Return**
1748
1749 Transport service identifier of **c** (if present)
1750
1751
1752 .. c:function:: const char * nvme_ctrl_get_host_traddr (nvme_ctrl_t c)
1753
1754 Host transport address of a controller
1755
1756 **Parameters**
1757
1758 ``nvme_ctrl_t c``
1759 Controller instance
1760
1761 **Return**
1762
1763 Host transport address of **c** (if present)
1764
1765
1766 .. c:function:: const char * nvme_ctrl_get_host_iface (nvme_ctrl_t c)
1767
1768 Host interface name of a controller
1769
1770 **Parameters**
1771
1772 ``nvme_ctrl_t c``
1773 Controller instance
1774
1775 **Return**
1776
1777 Host interface name of **c** (if present)
1778
1779
1780 .. c:function:: const char * nvme_ctrl_get_dhchap_host_key (nvme_ctrl_t c)
1781
1782 Return host key
1783
1784 **Parameters**
1785
1786 ``nvme_ctrl_t c``
1787 Controller to be checked
1788
1789 **Return**
1790
1791 DH-HMAC-CHAP host key or NULL if not set
1792
1793
1794 .. c:function:: const char * nvme_ctrl_get_cntlid (nvme_ctrl_t c)
1795
1796 Controller id
1797
1798 **Parameters**
1799
1800 ``nvme_ctrl_t c``
1801 Controller to be checked
1802
1803 **Return**
1804
1805 Controller id of **c**
1806
1807
1808 .. c:function:: void nvme_ctrl_set_dhchap_host_key (nvme_ctrl_t c, const char *key)
1809
1810 Set host key
1811
1812 **Parameters**
1813
1814 ``nvme_ctrl_t c``
1815 Host for which the key should be set
1816
1817 ``const char *key``
1818 DH-HMAC-CHAP Key to set or NULL to clear existing key
1819
1820
1821 .. c:function:: const char * nvme_ctrl_get_dhchap_key (nvme_ctrl_t c)
1822
1823 Return controller key
1824
1825 **Parameters**
1826
1827 ``nvme_ctrl_t c``
1828 Controller for which the key should be set
1829
1830 **Return**
1831
1832 DH-HMAC-CHAP controller key or NULL if not set
1833
1834
1835 .. c:function:: const char * nvme_ns_head_get_sysfs_dir (nvme_ns_head_t head)
1836
1837 sysfs dir of namespave head
1838
1839 **Parameters**
1840
1841 ``nvme_ns_head_t head``
1842 namespace head instance
1843
1844 **Return**
1845
1846 sysfs directory name of **head**
1847
1848
1849 .. c:function:: void nvme_ctrl_set_dhchap_key (nvme_ctrl_t c, const char *key)
1850
1851 Set controller key
1852
1853 **Parameters**
1854
1855 ``nvme_ctrl_t c``
1856 Controller for which the key should be set
1857
1858 ``const char *key``
1859 DH-HMAC-CHAP Key to set or NULL to clear existing key
1860
1861
1862 .. c:function:: const char * nvme_ctrl_get_keyring (nvme_ctrl_t c)
1863
1864 Return keyring
1865
1866 **Parameters**
1867
1868 ``nvme_ctrl_t c``
1869 Controller to be used for the lookup
1870
1871 **Return**
1872
1873 Keyring or NULL if not set
1874
1875
1876 .. c:function:: void nvme_ctrl_set_keyring (nvme_ctrl_t c, const char *keyring)
1877
1878 Set keyring
1879
1880 **Parameters**
1881
1882 ``nvme_ctrl_t c``
1883 Controller for which the keyring should be set
1884
1885 ``const char *keyring``
1886 Keyring name
1887
1888
1889 .. c:function:: const char * nvme_ctrl_get_tls_key_identity (nvme_ctrl_t c)
1890
1891 Return Derive TLS Identity
1892
1893 **Parameters**
1894
1895 ``nvme_ctrl_t c``
1896 Controller to be used for the lookup
1897
1898 **Return**
1899
1900 Derive TLS Identity or NULL if not set
1901
1902
1903 .. c:function:: void nvme_ctrl_set_tls_key_identity (nvme_ctrl_t c, const char *identity)
1904
1905 Set Derive TLS Identity
1906
1907 **Parameters**
1908
1909 ``nvme_ctrl_t c``
1910 Controller for which the key should be set
1911
1912 ``const char *identity``
1913 Derive TLS identity or NULL to clear existing key
1914
1915
1916 .. c:function:: const char * nvme_ctrl_get_tls_key (nvme_ctrl_t c)
1917
1918 Return Derive TLS PSK
1919
1920 **Parameters**
1921
1922 ``nvme_ctrl_t c``
1923 Controller to be used for the lookup
1924
1925 **Return**
1926
1927 Key in PSK interchange format or NULL if not set
1928
1929
1930 .. c:function:: void nvme_ctrl_set_tls_key (nvme_ctrl_t c, const char *key)
1931
1932 Set Derive TLS PSK
1933
1934 **Parameters**
1935
1936 ``nvme_ctrl_t c``
1937 Controller for which the key should be set
1938
1939 ``const char *key``
1940 Key in interchange format or NULL to clear existing key
1941
1942
1943 .. c:function:: struct nvme_fabrics_config * nvme_ctrl_get_config (nvme_ctrl_t c)
1944
1945 Fabrics configuration of a controller
1946
1947 **Parameters**
1948
1949 ``nvme_ctrl_t c``
1950 Controller instance
1951
1952 **Return**
1953
1954 Fabrics configuration of **c**
1955
1956
1957 .. c:function:: void nvme_ctrl_set_discovered (nvme_ctrl_t c, bool discovered)
1958
1959 Set the 'discovered' flag
1960
1961 **Parameters**
1962
1963 ``nvme_ctrl_t c``
1964 nvme_ctrl_t object
1965
1966 ``bool discovered``
1967 Value of the 'discovered' flag
1968
1969 **Description**
1970
1971 Set the 'discovered' flag of **c** to **discovered**
1972
1973
1974 .. c:function:: bool nvme_ctrl_is_discovered (nvme_ctrl_t c)
1975
1976 Returns the value of the 'discovered' flag
1977
1978 **Parameters**
1979
1980 ``nvme_ctrl_t c``
1981 Controller instance
1982
1983 **Return**
1984
1985 Value of the 'discovered' flag of **c**
1986
1987
1988 .. c:function:: void nvme_ctrl_set_persistent (nvme_ctrl_t c, bool persistent)
1989
1990 Set the 'persistent' flag
1991
1992 **Parameters**
1993
1994 ``nvme_ctrl_t c``
1995 Controller instance
1996
1997 ``bool persistent``
1998 value of the 'persistent' flag
1999
2000 **Description**
2001
2002 Set the 'persistent' flag of **c** to **persistent**
2003
2004
2005 .. c:function:: bool nvme_ctrl_is_persistent (nvme_ctrl_t c)
2006
2007 Returns the value of the 'persistent' flag
2008
2009 **Parameters**
2010
2011 ``nvme_ctrl_t c``
2012 Controller instance
2013
2014 **Return**
2015
2016 Value of the 'persistent' flag of **c**
2017
2018
2019 .. c:function:: void nvme_ctrl_set_discovery_ctrl (nvme_ctrl_t c, bool discovery)
2020
2021 Set the 'discovery_ctrl' flag
2022
2023 **Parameters**
2024
2025 ``nvme_ctrl_t c``
2026 Controller to be modified
2027
2028 ``bool discovery``
2029 value of the discovery_ctrl flag
2030
2031 **Description**
2032
2033 Sets the 'discovery_ctrl' flag in **c** to specify whether
2034 **c** connects to a discovery subsystem.
2035
2036
2037 .. c:function:: bool nvme_ctrl_is_discovery_ctrl (nvme_ctrl_t c)
2038
2039 Check the 'discovery_ctrl' flag
2040
2041 **Parameters**
2042
2043 ``nvme_ctrl_t c``
2044 Controller to be checked
2045
2046 **Description**
2047
2048 Returns the value of the 'discovery_ctrl' flag which specifies whether
2049 **c** connects to a discovery subsystem.
2050
2051 **Return**
2052
2053 Value of the 'discover_ctrl' flag
2054
2055
2056 .. c:function:: void nvme_ctrl_set_unique_discovery_ctrl (nvme_ctrl_t c, bool unique)
2057
2058 Set the 'unique_discovery_ctrl' flag
2059
2060 **Parameters**
2061
2062 ``nvme_ctrl_t c``
2063 Controller to be modified
2064
2065 ``bool unique``
2066 value of the unique_disc_ctrl flag
2067
2068 **Description**
2069
2070 Sets the 'unique_discovery_ctrl' flag in **c** to specify wheter
2071 **c** is a unique discovery controller
2072
2073
2074 .. c:function:: bool nvme_ctrl_is_unique_discovery_ctrl (nvme_ctrl_t c)
2075
2076 Check the 'unique_discovery_ctrl' flag
2077
2078 **Parameters**
2079
2080 ``nvme_ctrl_t c``
2081 Controller to be checked
2082
2083 **Return**
2084
2085 Value of the 'unique_discovery_ctrl' flag
2086
2087
2088 .. c:function:: int nvme_ctrl_identify (nvme_ctrl_t c, struct nvme_id_ctrl *id)
2089
2090 Issues an 'identify controller' command
2091
2092 **Parameters**
2093
2094 ``nvme_ctrl_t c``
2095 Controller instance
2096
2097 ``struct nvme_id_ctrl *id``
2098 Identify controller data structure
2099
2100 **Description**
2101
2102 Issues an 'identify controller' command to **c** and copies the
2103 data into **id**.
2104
2105 **Return**
2106
2107 0 on success or -1 on failure.
2108
2109
2110 .. c:function:: int nvme_disconnect_ctrl (nvme_ctrl_t c)
2111
2112 Disconnect a controller
2113
2114 **Parameters**
2115
2116 ``nvme_ctrl_t c``
2117 Controller instance
2118
2119 **Description**
2120
2121 Issues a 'disconnect' fabrics command to **c**
2122
2123 **Return**
2124
2125 0 on success, -1 on failure.
2126
2127
2128 .. c:function:: nvme_ctrl_t nvme_scan_ctrl (nvme_root_t r, const char *name)
2129
2130 Scan on a controller
2131
2132 **Parameters**
2133
2134 ``nvme_root_t r``
2135 nvme_root_t object
2136
2137 ``const char *name``
2138 Name of the controller
2139
2140 **Description**
2141
2142 Scans a controller with sysfs name **name** and add it to **r**.
2143
2144 **Return**
2145
2146 nvme_ctrl_t object
2147
2148
2149 .. c:function:: void nvme_rescan_ctrl (nvme_ctrl_t c)
2150
2151 Rescan an existing controller
2152
2153 **Parameters**
2154
2155 ``nvme_ctrl_t c``
2156 Controller instance
2157
2158
2159 .. c:function:: int nvme_init_ctrl (nvme_host_t h, nvme_ctrl_t c, int instance)
2160
2161 Initialize nvme_ctrl_t object for an existing controller.
2162
2163 **Parameters**
2164
2165 ``nvme_host_t h``
2166 nvme_host_t object
2167
2168 ``nvme_ctrl_t c``
2169 nvme_ctrl_t object
2170
2171 ``int instance``
2172 Instance number (e.g. 1 for nvme1)
2173
2174 **Return**
2175
2176 The ioctl() return code. Typically 0 on success.
2177
2178
2179 .. c:function:: void nvme_free_ctrl (struct nvme_ctrl *c)
2180
2181 Free controller
2182
2183 **Parameters**
2184
2185 ``struct nvme_ctrl *c``
2186 Controller instance
2187
2188
2189 .. c:function:: void nvme_unlink_ctrl (struct nvme_ctrl *c)
2190
2191 Unlink controller
2192
2193 **Parameters**
2194
2195 ``struct nvme_ctrl *c``
2196 Controller instance
2197
2198
2199 .. c:function:: const char * nvme_subsystem_get_nqn (nvme_subsystem_t s)
2200
2201 Retrieve NQN from subsystem
2202
2203 **Parameters**
2204
2205 ``nvme_subsystem_t s``
2206 nvme_subsystem_t object
2207
2208 **Return**
2209
2210 NQN of subsystem
2211
2212
2213 .. c:function:: const char * nvme_subsystem_get_sysfs_dir (nvme_subsystem_t s)
2214
2215 sysfs directory of an nvme_subsystem_t object
2216
2217 **Parameters**
2218
2219 ``nvme_subsystem_t s``
2220 nvme_subsystem_t object
2221
2222 **Return**
2223
2224 sysfs directory name of **s**
2225
2226
2227 .. c:function:: const char * nvme_subsystem_get_name (nvme_subsystem_t s)
2228
2229 sysfs name of an nvme_subsystem_t object
2230
2231 **Parameters**
2232
2233 ``nvme_subsystem_t s``
2234 nvme_subsystem_t object
2235
2236 **Return**
2237
2238 sysfs name of **s**
2239
2240
2241 .. c:function:: const char * nvme_subsystem_get_type (nvme_subsystem_t s)
2242
2243 Returns the type of a subsystem
2244
2245 **Parameters**
2246
2247 ``nvme_subsystem_t s``
2248 nvme_subsystem_t object
2249
2250 **Description**
2251
2252 Returns the subsystem type of **s**.
2253
2254 **Return**
2255
2256 'nvm' or 'discovery'
2257
2258
2259 .. c:function:: const char * nvme_subsystem_get_application (nvme_subsystem_t s)
2260
2261 Return the application string
2262
2263 **Parameters**
2264
2265 ``nvme_subsystem_t s``
2266 nvme_subsystem_t object
2267
2268 **Return**
2269
2270 Managing application string or NULL if not set.
2271
2272
2273 .. c:function:: void nvme_subsystem_set_application (nvme_subsystem_t s, const char *a)
2274
2275 Set the application string
2276
2277 **Parameters**
2278
2279 ``nvme_subsystem_t s``
2280 nvme_subsystem_t object
2281
2282 ``const char *a``
2283 application string
2284
2285 **Description**
2286
2287 Sets the managing application string for **s**.
2288
2289
2290 .. c:function:: const char * nvme_subsystem_get_iopolicy (nvme_subsystem_t s)
2291
2292 Return the IO policy of subsytem
2293
2294 **Parameters**
2295
2296 ``nvme_subsystem_t s``
2297 nvme_subsystem_t object
2298
2299 **Return**
2300
2301 IO policy used by current subsystem
2302
2303
2304 .. c:function:: const char * nvme_subsystem_get_model (nvme_subsystem_t s)
2305
2306 Return the model of subsystem
2307
2308 **Parameters**
2309
2310 ``nvme_subsystem_t s``
2311 nvme_subsystem_t object
2312
2313 **Return**
2314
2315 Model of the current subsystem
2316
2317
2318 .. c:function:: const char * nvme_subsystem_get_serial (nvme_subsystem_t s)
2319
2320 Return the serial number of subsystem
2321
2322 **Parameters**
2323
2324 ``nvme_subsystem_t s``
2325 nvme_subsystem_t object
2326
2327 **Return**
2328
2329 Serial number of the current subsystem
2330
2331
2332 .. c:function:: const char * nvme_subsystem_get_fw_rev (nvme_subsystem_t s)
2333
2334 Return the firmware rev of subsystem
2335
2336 **Parameters**
2337
2338 ``nvme_subsystem_t s``
2339 nvme_subsystem_t object
2340
2341 **Return**
2342
2343 Firmware revision of the current subsystem
2344
2345
2346 .. c:function:: int nvme_scan_topology (nvme_root_t r, nvme_scan_filter_t f, void *f_args)
2347
2348 Scan NVMe topology and apply filter
2349
2350 **Parameters**
2351
2352 ``nvme_root_t r``
2353 nvme_root_t object
2354
2355 ``nvme_scan_filter_t f``
2356 filter to apply
2357
2358 ``void *f_args``
2359 user-specified argument to **f**
2360
2361 **Description**
2362
2363 Scans the NVMe topology and filters out the resulting elements
2364 by applying **f**.
2365
2366 **Return**
2367
2368 0 on success, -1 on failure with errno set.
2369
2370
2371 .. c:function:: const char * nvme_host_get_hostnqn (nvme_host_t h)
2372
2373 Host NQN of an nvme_host_t object
2374
2375 **Parameters**
2376
2377 ``nvme_host_t h``
2378 nvme_host_t object
2379
2380 **Return**
2381
2382 Host NQN of **h**
2383
2384
2385 .. c:function:: const char * nvme_host_get_hostid (nvme_host_t h)
2386
2387 Host ID of an nvme_host_t object
2388
2389 **Parameters**
2390
2391 ``nvme_host_t h``
2392 nvme_host_t object
2393
2394 **Return**
2395
2396 Host ID of **h**
2397
2398
2399 .. c:function:: void nvme_host_release_fds (struct nvme_host *h)
2400
2401 Close all opened file descriptors under host
2402
2403 **Parameters**
2404
2405 ``struct nvme_host *h``
2406 nvme_host_t object
2407
2408 **Description**
2409
2410 Controller and Namespace objects cache the file descriptors
2411 of opened nvme devices. This API can be used to close and
2412 clear all cached fds under this host.
2413
2414
2415 .. c:function:: void nvme_free_host (nvme_host_t h)
2416
2417 Free nvme_host_t object
2418
2419 **Parameters**
2420
2421 ``nvme_host_t h``
2422 nvme_host_t object
2423
2424
2425 .. c:function:: nvme_root_t nvme_scan (const char *config_file)
2426
2427 Scan NVMe topology
2428
2429 **Parameters**
2430
2431 ``const char *config_file``
2432 Configuration file
2433
2434 **Return**
2435
2436 nvme_root_t object of found elements
2437
2438
2439 .. c:function:: int nvme_read_config (nvme_root_t r, const char *config_file)
2440
2441 Read NVMe JSON configuration file
2442
2443 **Parameters**
2444
2445 ``nvme_root_t r``
2446 nvme_root_t object
2447
2448 ``const char *config_file``
2449 JSON configuration file
2450
2451 **Description**
2452
2453 Read in the contents of **config_file** and merge them with
2454 the elements in **r**.
2455
2456 **Return**
2457
2458 0 on success, -1 on failure with errno set.
2459
2460
2461 .. c:function:: void nvme_refresh_topology (nvme_root_t r)
2462
2463 Refresh nvme_root_t object contents
2464
2465 **Parameters**
2466
2467 ``nvme_root_t r``
2468 nvme_root_t object
2469
2470 **Description**
2471
2472 Removes all elements in **r** and rescans the existing topology.
2473
2474
2475 .. c:function:: int nvme_update_config (nvme_root_t r)
2476
2477 Update JSON configuration
2478
2479 **Parameters**
2480
2481 ``nvme_root_t r``
2482 nvme_root_t object
2483
2484 **Description**
2485
2486 Updates the JSON configuration file with the contents of **r**.
2487
2488 **Return**
2489
2490 0 on success, -1 on failure.
2491
2492
2493 .. c:function:: int nvme_dump_config (nvme_root_t r)
2494
2495 Print the JSON configuration
2496
2497 **Parameters**
2498
2499 ``nvme_root_t r``
2500 nvme_root_t object
2501
2502 **Description**
2503
2504 Prints the current contents of the JSON configuration
2505 file to stdout.
2506
2507 **Return**
2508
2509 0 on success, -1 on failure.
2510
2511
2512 .. c:function:: int nvme_dump_tree (nvme_root_t r)
2513
2514 Dump internal object tree
2515
2516 **Parameters**
2517
2518 ``nvme_root_t r``
2519 nvme_root_t object
2520
2521 **Description**
2522
2523 Prints the internal object tree in JSON format
2524 to stdout.
2525
2526 **Return**
2527
2528 0 on success, -1 on failure.
2529
2530
2531 .. c:function:: char * nvme_get_attr (const char *d, const char *attr)
2532
2533 Read sysfs attribute
2534
2535 **Parameters**
2536
2537 ``const char *d``
2538 sysfs directory
2539
2540 ``const char *attr``
2541 sysfs attribute name
2542
2543 **Return**
2544
2545 String with the contents of **attr** or ``NULL`` in case of an empty value
2546 or in case of an error (indicated by non-zero errno code).
2547
2548
2549 .. c:function:: char * nvme_get_subsys_attr (nvme_subsystem_t s, const char *attr)
2550
2551 Read subsystem sysfs attribute
2552
2553 **Parameters**
2554
2555 ``nvme_subsystem_t s``
2556 nvme_subsystem_t object
2557
2558 ``const char *attr``
2559 sysfs attribute name
2560
2561 **Return**
2562
2563 String with the contents of **attr** or ``NULL`` in case of an empty value
2564 or in case of an error (indicated by non-zero errno code).
2565
2566
2567 .. c:function:: char * nvme_get_ctrl_attr (nvme_ctrl_t c, const char *attr)
2568
2569 Read controller sysfs attribute
2570
2571 **Parameters**
2572
2573 ``nvme_ctrl_t c``
2574 Controller instance
2575
2576 ``const char *attr``
2577 sysfs attribute name
2578
2579 **Return**
2580
2581 String with the contents of **attr** or ``NULL`` in case of an empty value
2582 or in case of an error (indicated by non-zero errno code).
2583
2584
2585 .. c:function:: char * nvme_get_ns_attr (nvme_ns_t n, const char *attr)
2586
2587 Read namespace sysfs attribute
2588
2589 **Parameters**
2590
2591 ``nvme_ns_t n``
2592 nvme_ns_t object
2593
2594 ``const char *attr``
2595 sysfs attribute name
2596
2597 **Return**
2598
2599 String with the contents of **attr** or ``NULL`` in case of an empty value
2600 or in case of an error (indicated by non-zero errno code).
2601
2602
2603 .. c:function:: nvme_ns_t nvme_subsystem_lookup_namespace (struct nvme_subsystem *s, __u32 nsid)
2604
2605 lookup namespace by NSID
2606
2607 **Parameters**
2608
2609 ``struct nvme_subsystem *s``
2610 nvme_subsystem_t object
2611
2612 ``__u32 nsid``
2613 Namespace id
2614
2615 **Return**
2616
2617 nvme_ns_t of the namespace with id **nsid** in subsystem **s**
2618
2619
2620 .. c:function:: void nvme_subsystem_release_fds (struct nvme_subsystem *s)
2621
2622 Close all opened fds under subsystem
2623
2624 **Parameters**
2625
2626 ``struct nvme_subsystem *s``
2627 nvme_subsystem_t object
2628
2629 **Description**
2630
2631 Controller and Namespace objects cache the file descriptors
2632 of opened nvme devices. This API can be used to close and
2633 clear all cached fds under this subsystem.
2634
2635
2636 .. c:function:: char * nvme_get_path_attr (nvme_path_t p, const char *attr)
2637
2638 Read path sysfs attribute
2639
2640 **Parameters**
2641
2642 ``nvme_path_t p``
2643 nvme_path_t object
2644
2645 ``const char *attr``
2646 sysfs attribute name
2647
2648 **Return**
2649
2650 String with the contents of **attr** or ``NULL`` in case of an empty value
2651 or in case of an error (indicated by non-zero errno code).
2652
2653
2654 .. c:function:: nvme_ns_t nvme_scan_namespace (const char *name)
2655
2656 scan namespace based on sysfs name
2657
2658 **Parameters**
2659
2660 ``const char *name``
2661 sysfs name of the namespace to scan
2662
2663 **Return**
2664
2665 nvme_ns_t object or NULL if not found.
2666
2667
2668 .. c:function:: const char * nvme_host_get_hostsymname (nvme_host_t h)
2669
2670 Get the host's symbolic name
2671
2672 **Parameters**
2673
2674 ``nvme_host_t h``
2675 Host for which the symbolic name should be returned.
2676
2677 **Return**
2678
2679 The symbolic name or NULL if a symbolic name hasn't been
2680 configure.
2681
2682
2683 .. c:function:: void nvme_host_set_hostsymname (nvme_host_t h, const char *hostsymname)
2684
2685 Set the host's symbolic name
2686
2687 **Parameters**
2688
2689 ``nvme_host_t h``
2690 Host for which the symbolic name should be set.
2691
2692 ``const char *hostsymname``
2693 Symbolic name
2694
2695