Debian Codegraph @

upstream/debian-unstable/man3/sd_hwdb_new.3

raw
1 '\" t
2 .TH "SD_HWDB_NEW" "3" "" "systemd 261~rc3" "sd_hwdb_new"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_hwdb_new, sd_hwdb_new_from_path, sd_hwdb_ref, sd_hwdb_unref \- Create a new hwdb object and create or destroy references to it
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-hwdb\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_hwdb_new('u
32 .BI "int sd_hwdb_new(sd_hwdb\ **" "hwdb" ");"
33 .HP \w'int\ sd_hwdb_new_from_path('u
34 .BI "int sd_hwdb_new_from_path(const\ char\ *" "path" ", sd_hwdb\ **" "hwdb" ");"
35 .HP \w'sd_hwdb*\ sd_hwdb_ref('u
36 .BI "sd_hwdb* sd_hwdb_ref(sd_hwdb\ *" "hwdb" ");"
37 .HP \w'sd_hwdb*\ sd_hwdb_unref('u
38 .BI "sd_hwdb* sd_hwdb_unref(sd_hwdb\ *" "hwdb" ");"
39 .SH "DESCRIPTION"
40 .PP
41 \fBsd_hwdb_new()\fR
42 creates a new hwdb object to access the binary hwdb database\&. Upon initialization, the file containing the binary representation of the hardware database is located and opened\&. The new object is returned in
43 \fIhwdb\fR\&.
44 .PP
45 \fBsd_hwdb_new_from_path()\fR
46 may be used to specify the path from which the binary hardware database should be opened\&.
47 .PP
48 The
49 \fIhwdb\fR
50 object is reference counted\&.
51 \fBsd_hwdb_ref()\fR
52 and
53 \fBsd_hwdb_unref()\fR
54 may be used to get a new reference or destroy an existing reference to an object\&. The caller must dispose of the reference acquired with
55 \fBsd_hwdb_new()\fR
56 by calling
57 \fBsd_hwdb_unref()\fR
58 when done with the object\&.
59 .PP
60 Use
61 \fBsd_hwdb_seek\fR(3),
62 \fBsd_hwdb_get\fR(3), and
63 \fBsd_hwdb_enumerate\fR(3)
64 to access entries\&.
65 .SH "RETURN VALUE"
66 .PP
67 On success,
68 \fBsd_hwdb_new()\fR
69 and
70 \fBsd_hwdb_new_from_path()\fR
71 return a non\-negative integer\&. On failure, a negative errno\-style error code is returned\&.
72 .PP
73 \fBsd_hwdb_ref()\fR
74 always returns the argument\&.
75 .PP
76 \fBsd_hwdb_unref()\fR
77 always returns
78 \fBNULL\fR\&.
79 .SS "Errors"
80 .PP
81 Returned errors may indicate the following problems:
82 .PP
83 \fB\-ENOENT\fR
84 .RS 4
85 The binary hardware database file could not be located\&. See
86 \fBsystemd-hwdb\fR(8)
87 for more information\&.
88 .sp
89 Added in version 246\&.
90 .RE
91 .PP
92 \fB\-EINVAL\fR
93 .RS 4
94 The located binary hardware database file is in an incompatible format\&.
95 .sp
96 Added in version 246\&.
97 .RE
98 .PP
99 \fB\-ENOMEM\fR
100 .RS 4
101 Memory allocation failed\&.
102 .sp
103 Added in version 246\&.
104 .RE
105 .SH "NOTES"
106 .PP
107 Functions described here are available as a shared library, which can be compiled against and linked to with the
108 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
109 file\&.
110 .PP
111 The code described here uses
112 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
113 \fBsetenv\fR(3)
114 from a parallel thread\&. It is recommended to only do calls to
115 \fBsetenv()\fR
116 from an early phase of the program when no other threads have been started\&.
117 .SH "HISTORY"
118 .PP
119 \fBsd_hwdb_new()\fR,
120 \fBsd_hwdb_ref()\fR, and
121 \fBsd_hwdb_unref()\fR
122 were added in version 246\&.
123 .PP
124 \fBsd_hwdb_new_from_path()\fR
125 was added in version 252\&.
126 .SH "SEE ALSO"
127 .PP
128 \fBsystemd\fR(1), \fBsystemd-udevd.service\fR(8), \fBsd-hwdb\fR(3), \fBsystemd-hwdb\fR(8)