![]() |
![]() |
![]() |
umockdev Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy |
struct UMockdevTestbed; UMockdevTestbed * umockdev_testbed_new (void
); gchar * umockdev_testbed_add_device (UMockdevTestbed *self
,const gchar *subsystem
,const gchar *name
,const gchar *parent
,...
); gchar * umockdev_testbed_add_devicev (UMockdevTestbed *self
,const gchar *subsystem
,const gchar *name
,const gchar *parent
,gchar **attributes
,gchar **properties
); void umockdev_testbed_remove_device (UMockdevTestbed *self
,const gchar *syspath
); gchar * umockdev_testbed_get_root_dir (UMockdevTestbed *self
); gchar * umockdev_testbed_get_sys_dir (UMockdevTestbed *self
); void umockdev_testbed_set_attribute (UMockdevTestbed *self
,const gchar *devpath
,const gchar *name
,const gchar *value
); void umockdev_testbed_set_attribute_int (UMockdevTestbed *self
,const gchar *devpath
,const gchar *name
,gint value
); void umockdev_testbed_set_attribute_hex (UMockdevTestbed *self
,const gchar *devpath
,const gchar *name
,guint value
); void umockdev_testbed_set_attribute_binary (UMockdevTestbed *self
,const gchar *devpath
,const gchar *name
,guint8 *value
,int value_length1
); void umockdev_testbed_set_attribute_link (UMockdevTestbed *self
,const gchar *devpath
,const gchar *name
,const gchar *value
); void umockdev_testbed_set_property (UMockdevTestbed *self
,const gchar *devpath
,const gchar *name
,const gchar *value
); void umockdev_testbed_set_property_int (UMockdevTestbed *self
,const gchar *devpath
,const gchar *name
,gint value
); void umockdev_testbed_set_property_hex (UMockdevTestbed *self
,const gchar *devpath
,const gchar *name
,guint value
); void umockdev_testbed_uevent (UMockdevTestbed *self
,const gchar *devpath
,const gchar *action
); gboolean umockdev_testbed_add_from_string (UMockdevTestbed *self
,const gchar *data
,GError **error
); gboolean umockdev_testbed_add_from_file (UMockdevTestbed *self
,const gchar *path
,GError **error
); gboolean umockdev_testbed_load_ioctl (UMockdevTestbed *self
,const gchar *dev
,const gchar *recordfile
,GError **error
); gboolean umockdev_testbed_load_script (UMockdevTestbed *self
,const gchar *dev
,const gchar *recordfile
,GError **error
); gboolean umockdev_testbed_load_socket_script (UMockdevTestbed *self
,const gchar *path
,gint type
,const gchar *recordfile
,GError **error
); gint umockdev_testbed_get_dev_fd (UMockdevTestbed *self
,const gchar *devnode
); void umockdev_testbed_clear (UMockdevTestbed *self
); void umockdev_testbed_disable (UMockdevTestbed *self
); void umockdev_testbed_enable (UMockdevTestbed *self
);
Please see README.rst about an overview of the parts of umockdev, and how they fit together.
struct UMockdevTestbed;
The UMockdevTestbed class builds a temporary sandbox for mock devices. You can add a number of devices including arbitrary sysfs attributes and udev properties, and then run your software in that test bed that is independent of the actual hardware it is running on. With this you can simulate particular hardware in virtual environments up to some degree, without needing any particular privileges or disturbing the whole system.
You can either add devices by specifying individual device paths,
properties, and attributes, or use the umockdev-record tool to create a human
readable/editable record of a real device (and all its parents) and load
that into the testbed with umockdev_testbed_add_from_string()
.
Instantiating a UMockdevTestbed object creates a temporary directory with an empty sysfs tree and sets the $UMOCKDEV_DIR environment variable so that programs subsequently started under umockdev-wrapper will use the test bed instead of the system's real sysfs.
UMockdevTestbed * umockdev_testbed_new (void
);
Create a new UMockdevTestbed object. This is initially empty, call methods like umockdev_testbed_add_device or umockdev_testbed_add_from_string to fill it.
Returns : |
The newly created UMockdevTestbed object. |
gchar * umockdev_testbed_add_device (UMockdevTestbed *self
,const gchar *subsystem
,const gchar *name
,const gchar *parent
,...
);
Add a new device to the testbed. A Linux kernel device always has a
subsystem (such as "usb" or "pci"), and a device name. The test bed only
builds a very simple sysfs structure without nested namespaces, so it
requires device names to be unique. Some gudev client programs might make
assumptions about the name (e. g. a SCSI disk block device should be called
sdaN). A device also has an arbitrary number of sysfs attributes and udev
properties; usually you should specify them upon creation, but it is also
possible to change them later on with umockdev_testbed_set_attribute()
and
umockdev_testbed_set_property()
.
Example:
1 2 3 |
umockdev_testbed_add_device (testbed, "usb", "dev1", NULL, "idVendor", "0815", "idProduct", "AFFE", NULL, "ID_MODEL", "KoolGadget", NULL); |
|
A UMockdevTestbed. |
|
The subsystem name, e. g. "usb" |
|
The device name; arbitrary, but needs to be unique within the testbed |
|
device path of the parent device. Use NULL for a
top-level device. [allow-none]
|
|
Arbitrarily many pairs of sysfs attributes (alternating names and
values), terminated by NULL , followed by arbitrarily many pairs of udev
properties, terminated by another NULL . |
Returns : |
The sysfs path for the newly created device. Free with g_free() . |
gchar * umockdev_testbed_add_devicev (UMockdevTestbed *self
,const gchar *subsystem
,const gchar *name
,const gchar *parent
,gchar **attributes
,gchar **properties
);
This method is mostly meant for language bindings (where it is named
umockdev_testbed_add_device()
). For C programs it is usually more convenient to
use umockdev_testbed_add_device()
.
Add a new device to the testbed. A Linux kernel device always has a
subsystem (such as "usb" or "pci"), and a device name. The test bed only
builds a very simple sysfs structure without nested namespaces, so it
requires device names to be unique. Some gudev client programs might make
assumptions about the name (e. g. a SCSI disk block device should be called
sdaN). A device also has an arbitrary number of sysfs attributes and udev
properties; usually you should specify them upon creation, but it is also
possible to change them later on with umockdev_testbed_set_attribute()
and
umockdev_testbed_set_property()
.
|
A UMockdevTestbed. |
|
The subsystem name, e. g. "usb" |
|
The device name; arbitrary, but needs to be unique within the testbed |
|
device path of the parent device. Use NULL for a
top-level device. [allow-none]
|
|
A list of device sysfs attributes, alternating names and
values, terminated with NULL :
{ "key1", "value1", "key2", "value2", ..., NULL }. [array zero-terminated=1]
|
|
A list of device udev properties; same format as attributes . [array zero-terminated=1]
|
Returns : |
The sysfs path for the newly created device. Free with g_free() .
Rename to: umockdev_testbed_add_device |
void umockdev_testbed_remove_device (UMockdevTestbed *self
,const gchar *syspath
);
Remove a device from the testbed. This removes the sysfs directory, the
/sys/class/ link, the device node, and all other information related to
it. Note that this will also remove all child devices (i. e.
subdirectories of syspath
).
|
A UMockdevTestbed. |
|
Sysfs path of device |
gchar * umockdev_testbed_get_root_dir (UMockdevTestbed *self
);
Get the root directory for the testbed.
|
A UMockdevTestbed. |
Returns : |
The testbed's root directory. |
gchar * umockdev_testbed_get_sys_dir (UMockdevTestbed *self
);
Get the sysfs directory for the testbed.
|
A UMockdevTestbed. |
Returns : |
The testbed's sysfs directory. |
void umockdev_testbed_set_attribute (UMockdevTestbed *self
,const gchar *devpath
,const gchar *name
,const gchar *value
);
Set a text sysfs attribute for a device.
|
A UMockdevTestbed. |
|
The full device path, as returned by #umockdev_testbed_add_device()
|
|
Attribute name |
|
Attribute string value |
void umockdev_testbed_set_attribute_int (UMockdevTestbed *self
,const gchar *devpath
,const gchar *name
,gint value
);
Set an integer sysfs attribute for a device.
|
A UMockdevTestbed. |
|
The full device path, as returned by #umockdev_testbed_add_device()
|
|
Attribute name |
|
Attribute integer value |
void umockdev_testbed_set_attribute_hex (UMockdevTestbed *self
,const gchar *devpath
,const gchar *name
,guint value
);
Set an integer sysfs attribute for a device. Set an integer udev
property for a device. value
is interpreted as a hexadecimal number.
For example, for value==31 this sets the attribute contents to "1f".
|
A UMockdevTestbed. |
|
The full device path, as returned by #umockdev_testbed_add_device()
|
|
Attribute name |
|
Attribute integer value |
void umockdev_testbed_set_attribute_binary (UMockdevTestbed *self
,const gchar *devpath
,const gchar *name
,guint8 *value
,int value_length1
);
Set a binary sysfs attribute for a device.
|
A UMockdevTestbed. |
|
The full device path, as returned by #umockdev_testbed_add_device()
|
|
Attribute name |
|
Attribute binary value |
|
Length of value in bytes. |
void umockdev_testbed_set_attribute_link (UMockdevTestbed *self
,const gchar *devpath
,const gchar *name
,const gchar *value
);
Set a symlink sysfs attribute for a device; this is primarily important for setting "driver" links.
|
A UMockdevTestbed. |
|
The full device path, as returned by #umockdev_testbed_add_device()
|
|
Attribute name |
|
Attribute link target value |
void umockdev_testbed_set_property (UMockdevTestbed *self
,const gchar *devpath
,const gchar *name
,const gchar *value
);
Set a string udev property for a device.
|
A UMockdevTestbed. |
|
The full device path, as returned by #umockdev_testbed_add_device()
|
|
Property name |
|
Property string value |
void umockdev_testbed_set_property_int (UMockdevTestbed *self
,const gchar *devpath
,const gchar *name
,gint value
);
Set an integer udev property for a device.
|
A UMockdevTestbed. |
|
The full device path, as returned by #umockdev_testbed_add_device()
|
|
Property name |
|
Property integer value |
void umockdev_testbed_set_property_hex (UMockdevTestbed *self
,const gchar *devpath
,const gchar *name
,guint value
);
Set an integer udev property for a device. value
is interpreted as a
hexadecimal number. For example, for value==31 this sets the property's
value to "1f".
|
A UMockdevTestbed. |
|
The full device path, as returned by #umockdev_testbed_add_device()
|
|
Property name |
|
Property integer value |
void umockdev_testbed_uevent (UMockdevTestbed *self
,const gchar *devpath
,const gchar *action
);
Generate an uevent for a device.
|
A UMockdevTestbed. |
|
The full device path, as returned by #umockdev_testbed_add_device()
|
|
"add", "remove", or "change" |
gboolean umockdev_testbed_add_from_string (UMockdevTestbed *self
,const gchar *data
,GError **error
);
Add a set of devices to the testbed from a textual description. This reads the format generated by the umockdev-record tool.
Each paragraph defines one device. A line starts with a type tag (like 'E'), followed by a colon, followed by either a value or a "key=value" assignment, depending on the type tag. A device description must start with a 'P:' line. Available type tags are:
/devices/
; must occur exactly once at the
start of device definition/dev/
prefix); if contents is given (encoded in a
continuous hex string), it creates a
/dev/devname
in the mock environment with
the given contents, otherwise the created dev file will be a
pty; see umockdev_testbed_get_dev_fd for details./dev/
prefix); ignored right
now.
|
A UMockdevTestbed. |
|
Description of the device(s) as generated with umockdev-record |
|
return location for a GError, or NULL
|
Returns : |
TRUE on success, FALSE if the data is invalid and an error
occurred. |
gboolean umockdev_testbed_add_from_file (UMockdevTestbed *self
,const gchar *path
,GError **error
);
Add a set of devices to the testbed from a textual description. This
reads a file with the format generated by the umockdev-record tool, and
is mostly a convenience wrapper around
umockdev_testbed_add_from_string
.
|
A UMockdevTestbed. |
|
Path to file with description of the device(s) as generated with umockdev-record |
|
return location for a GError, or NULL
|
Returns : |
TRUE on success, FALSE if the path cannot be read or thhe
data is invalid and an error occurred. |
gboolean umockdev_testbed_load_ioctl (UMockdevTestbed *self
,const gchar *dev
,const gchar *recordfile
,GError **error
);
Load an ioctl record file for a particular device into the testbed. ioctl records can be created with umockdev-record --ioctl. They can optionally be xz compressed to save space (but then are required to have an .xz file name suffix).
|
A UMockdevTestbed. |
|
Device path (/dev/...) for which to load the ioctl record.
NULL is valid; in this case the ioctl record is associated with
the device node it was recorded from. |
|
Path of the ioctl record file. |
|
return location for a GError, or NULL
|
Returns : |
TRUE on success, FALSE if the data is invalid and an error
occurred. |
gboolean umockdev_testbed_load_script (UMockdevTestbed *self
,const gchar *dev
,const gchar *recordfile
,GError **error
);
Load a script record file for a particular device into the testbed. script records can be created with umockdev-record --script.
|
A UMockdevTestbed. |
|
Device path (/dev/...) for which to load the script record. |
|
Path of the script record file. |
|
return location for a GError, or NULL
|
Returns : |
TRUE on success, FALSE if recordfile is invalid and an error
occurred. |
gboolean umockdev_testbed_load_socket_script (UMockdevTestbed *self
,const gchar *path
,gint type
,const gchar *recordfile
,GError **error
);
Add an Unix socket to the testbed that is backed by a recorded script.
Clients can connect to the socket using path
(i. e. without the testbed
prefix).
|
A UMockdevTestbed. |
|
Unix socket path |
|
Unix socket type (SOCK_STREAM, SOCK_DGRAM) |
|
Path of the script record file. |
|
return location for a GError, or NULL
|
Returns : |
TRUE on success, FALSE if the path or type are
invalid and an error occurred. |
gint umockdev_testbed_get_dev_fd (UMockdevTestbed *self
,const gchar *devnode
);
Simulated devices without a pre-defined contents are backed by a
stream-like device node (PTY). Return the file descriptor
for accessing their "master" side, i. e. the end that gets
controlled by test suites. The tested program opens the "slave" side,
which is just openening the device specified by devnode
, e. g.
/dev/ttyUSB2. Once that happened, your test can directly communicate
with the tested program over that descriptor.
|
A UMockdevTestbed. |
|
Device node name ("/dev/...") |
Returns : |
File descriptor for communicating with clients that connect to
devnode , or -1 if devnode does not exist or is not a
simulated stream device. This must not be closed! |
void umockdev_testbed_clear (UMockdevTestbed *self
);
Remove all added devices from testbed directory. After that, the umockdev root directory will be in the same state as directly after the constructor.
|
A UMockdevTestbed. |
void umockdev_testbed_disable (UMockdevTestbed *self
);
Disable the testbed. This can be used for temporarily switching back to
the real /sys and /dev without having to destroy or change $UMOCKDEV_DIR
and the UMockdevTestbed instance. Use
to
re-enable the testbed.
umockdev_testbed_enable()
|
A UMockdevTestbed. |
void umockdev_testbed_enable (UMockdevTestbed *self
);
Re-enable the testbed after @
.
umockdev_testbed_disable()
|
A UMockdevTestbed. |