From: Ben Pfaff Date: Tue, 28 Jul 2009 19:38:14 +0000 (-0700) Subject: rtnetlink: Document. X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d81c0ac56d42039d9bccbf4a65d4eb18f9fa654b;p=openvswitch rtnetlink: Document. --- diff --git a/lib/netdev-linux.c b/lib/netdev-linux.c index fbca6760..95d9d907 100644 --- a/lib/netdev-linux.c +++ b/lib/netdev-linux.c @@ -1605,6 +1605,15 @@ static void rtnetlink_report_change(const struct nlmsghdr *, struct nlattr *attrs[]); static void rtnetlink_report_notify_error(void); +/* Registers 'cb' to be called with auxiliary data 'aux' with network device + * change notifications. The notifier is stored in 'notifier', which the + * caller must not modify or free. + * + * This is probably not the function that you want. You should probably be + * using dpif_port_poll() or netdev_monitor_create(), which unlike this + * function are not Linux-specific. + * + * Returns 0 if successful, otherwise a positive errno value. */ int rtnetlink_notifier_register(struct rtnetlink_notifier *notifier, rtnetlink_notify_func *cb, void *aux) @@ -1629,6 +1638,8 @@ rtnetlink_notifier_register(struct rtnetlink_notifier *notifier, return 0; } +/* Cancels notification on 'notifier', which must have previously been + * registered with lxnetdev_notifier_register(). */ void rtnetlink_notifier_unregister(struct rtnetlink_notifier *notifier) { @@ -1639,6 +1650,8 @@ rtnetlink_notifier_unregister(struct rtnetlink_notifier *notifier) } } +/* Calls all of the registered notifiers, passing along any as-yet-unreported + * netdev change events. */ void rtnetlink_notifier_run(void) { @@ -1681,6 +1694,8 @@ rtnetlink_notifier_run(void) } } +/* Causes poll_block() to wake up when network device change notifications are + * ready. */ void rtnetlink_notifier_wait(void) { diff --git a/lib/netdev-linux.h b/lib/netdev-linux.h index 9c0a2e02..42ea380a 100644 --- a/lib/netdev-linux.h +++ b/lib/netdev-linux.h @@ -22,6 +22,8 @@ #include "list.h" +/* A digested version of an rtnetlink message sent down by the kernel to + * indicate that a network device has been created or destroyed or changed. */ struct rtnetlink_change { /* Copied from struct nlmsghdr. */ int nlmsg_type; /* e.g. RTM_NEWLINK, RTM_DELLINK. */ @@ -34,8 +36,12 @@ struct rtnetlink_change { int master_ifindex; /* Ifindex of datapath master (0 if none). */ }; -typedef void rtnetlink_notify_func(const struct rtnetlink_change *, - void *aux); +/* Function called to report that a netdev has changed. 'change' describes the + * specific change. It may be null if the buffer of change information + * overflowed, in which case the function must assume that every device may + * have changed. 'aux' is as specified in the call to + * lxnetdev_notifier_register(). */ +typedef void rtnetlink_notify_func(const struct rtnetlink_change *, void *aux); struct rtnetlink_notifier { struct list node;