lkml.org 
[lkml]   [2019]   [Aug]   [30]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    From
    Subjectwatch_devices(2) manpage
    Date
    '\" t
    .\" Copyright (c) 2019 David Howells <dhowells@redhat.com>
    .\"
    .\" %%%LICENSE_START(VERBATIM)
    .\" Permission is granted to make and distribute verbatim copies of this
    .\" manual provided the copyright notice and this permission notice are
    .\" preserved on all copies.
    .\"
    .\" Permission is granted to copy and distribute modified versions of this
    .\" manual under the conditions for verbatim copying, provided that the
    .\" entire resulting derived work is distributed under the terms of a
    .\" permission notice identical to this one.
    .\"
    .\" Since the Linux kernel and libraries are constantly changing, this
    .\" manual page may be incorrect or out-of-date. The author(s) assume no
    .\" responsibility for errors or omissions, or for damages resulting from
    .\" the use of the information contained herein. The author(s) may not
    .\" have taken the same level of care in the production of this manual,
    .\" which is licensed free of charge, as they might when working
    .\" professionally.
    .\"
    .\" Formatted or processed versions of this manual, if unaccompanied by
    .\" the source, must acknowledge the copyright and authors of this work.
    .\" %%%LICENSE_END
    .\"
    .TH WATCH_DEVICES 2 2019-08-29 "Linux" "Linux Programmer's Manual"
    .SH NAME
    watch_devices \- Watch for global device notifications
    .SH SYNOPSIS
    .nf
    .B #include <linux/watch_queue.h>
    .br
    .B #include <unistd.h>
    .br
    .BI "int watch_devices(int " watch_fd ", int " watch_id ", unsigned int " flags );
    .fi
    .PP
    .IR Note :
    There are no glibc wrappers for these system calls.
    .SH DESCRIPTION
    .PP
    .BR watch_devices ()
    attaches a watch on the global device notification source to a previously
    opened and configured watch queue. See
    .BR watch_queue (7)
    for more information on how to set up and use those.
    .PP
    The global device notification source is provided with events from a number of
    sources, including block device errors and USB events. Each notification type
    has a specific format.

    .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
    .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
    .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
    .SS Block Device Notifications
    Events on block devices, such as I/O errors are posted to any watching queues.
    The message format is:
    .PP
    .in +4n
    .EX
    struct block_notification {
    struct watch_notification watch;
    __u64 dev;
    __u64 sector;
    };
    .EE
    .in
    .PP
    The
    .I watch.type
    field will be set to
    .BR WATCH_TYPE_BLOCK_NOTIFY ,
    the
    .I watch.subtype
    field will contain a constant that indicates the particular event that occurred
    and the watch_id passed to watch_devices() will be placed in
    .I watch.info
    in the ID field.
    .PP
    .I dev
    will contain the major and minor device numbers in
    .B dev_t
    form and
    .I sector
    will contain the first sector the notification pertains to.
    .PP
    The following events are defined:
    .PP
    .in +4n
    .TS
    lB l.
    NOTIFY_BLOCK_ERROR_TIMEOUT
    NOTIFY_BLOCK_ERROR_NO_SPACE
    NOTIFY_BLOCK_ERROR_RECOVERABLE_TRANSPORT
    NOTIFY_BLOCK_ERROR_CRITICAL_TARGET
    NOTIFY_BLOCK_ERROR_CRITICAL_NEXUS
    NOTIFY_BLOCK_ERROR_CRITICAL_MEDIUM
    NOTIFY_BLOCK_ERROR_PROTECTION
    NOTIFY_BLOCK_ERROR_KERNEL_RESOURCE
    NOTIFY_BLOCK_ERROR_DEVICE_RESOURCE
    NOTIFY_BLOCK_ERROR_IO
    .TE
    .in
    .PP
    All of which indicate error conditions.

    .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
    .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
    .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
    .SS USB Device Notifications
    Events on USB devices, such as I/O errors are posted to any watching queues.
    The message format is:
    .PP
    .in +4n
    .EX
    struct usb_notification {
    struct watch_notification watch;
    __u32 error;
    __u32 reserved;
    __u8 name_len;
    __u8 name[0];
    };
    .EE
    .in
    .PP
    The
    .I watch.type
    field will be set to
    .BR WATCH_TYPE_USB_NOTIFY ,
    the
    .I watch.subtype
    field will contain a constant that indicates the particular event that occurred
    and the watch_id passed to watch_devices() will be placed in
    .I watch.info
    in the ID field.
    .PP
    .IR name " and " name_len
    indicates the textual name of the USB device that originated the notification.
    The name will be truncated to
    .B USB_NOTIFICATION_MAX_NAME_LEN
    if it is longer than that.
    .PP
    The following subtypes are currently defined:
    .TP
    .B NOTIFY_USB_DEVICE_ADD
    A new USB device has been plugged in.
    .TP
    .B NOTIFY_USB_DEVICE_REMOVE
    A USB device has been unplugged.
    .TP
    .B NOTIFY_USB_BUS_ADD
    A new USB bus is now available.
    .TP
    .B NOTIFY_USB_BUS_REMOVE
    A USB bus has been removed.
    .TP
    .B NOTIFY_USB_DEVICE_RESET
    A USB device has been reset.
    .TP
    .B NOTIFY_USB_DEVICE_ERROR
    A USB device has generated an error; a suitable error code will have been
    placed in
    .IR error .


    .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
    .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
    .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
    .SH RETURN VALUE
    On success, the function returns 0. On error, \-1 is returned, and
    .I errno
    is set appropriately.
    .SH ERRORS
    The following errors may be returned:
    .TP
    .B EBADF
    .I watch_fd
    is an invalid file descriptor.
    .TP
    .B EBADSLT
    The watch does not exist and so cannot be removed.
    .TP
    .B EBUSY
    The source is already attached to the watch device instance specified by
    .I watch_fd
    and so cannot be added.
    .TP
    .B EINVAL
    .I watch_fd
    does not refer to a watch_queue device file.
    .TP
    .B EINVAL
    .IR watch_fd " or " watch_id
    is out of range.
    .TP
    .B EINVAL
    Unsupported
    .I flags
    set.
    .TP
    .B ENOMEM
    Insufficient memory available to allocate a watch record.
    .TP
    .B EPERM
    The caller does not have the required privileges.
    .SH CONFORMING TO
    These functions are Linux-specific and should not be used in programs intended
    to be portable.
    .SH VERSIONS
    The notification queue driver first appeared in v??? of the Linux kernel.
    .SH NOTES
    Glibc does not (yet) provide a wrapper for the
    .BR watch_devices "()"
    system call; call it using
    .BR syscall (2).
    .SH SEE ALSO
    .BR watch_queue (7)

    \
     
     \ /
      Last update: 2019-08-30 16:16    [W:4.493 / U:1.560 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site