man/man3/libnetlink.3

   1 .TH libnetlink 3
   2 .SH NAME
   3 libnetlink \- A library for accessing the netlink service
   4 .SH SYNOPSIS
   5 .nf
   6 #include <asm/types.h>
   7 .br
   8 #include <libnetlink.h>
   9 .br
  10 #include <linux/netlink.h>
  11 .br
  12 #include <linux/rtnetlink.h>
  13 .sp
  14 int rtnl_open(struct rtnl_handle *rth, unsigned subscriptions)
  15 .sp
  16 int rtnl_wilddump_request(struct rtnl_handle *rth, int family, int type)
  17 .sp
  18 int rtnl_send(struct rtnl_handle *rth, char *buf, int len)
  19 .sp
  20 int rtnl_dump_request(struct rtnl_handle *rth, int type, void *req, int len)
  21 .sp
  22 int rtnl_dump_filter(struct rtnl_handle *rth,
  23                      int (*filter)(struct sockaddr_nl *, struct nlmsghdr *n, void *),
  24                      void *arg1,
  25                      int (*junk)(struct sockaddr_nl *,struct nlmsghdr *n, void *),
  26                      void *arg2)
  27 .sp
  28 int rtnl_talk(struct rtnl_handle *rtnl, struct nlmsghdr *n, pid_t peer,
  29               unsigned groups, struct nlmsghdr *answer,
  30 .br
  31               int (*junk)(struct sockaddr_nl *,struct nlmsghdr *n, void *),
  32 .br
  33               void *jarg)
  34 .sp
  35 int rtnl_listen(struct rtnl_handle *rtnl,
  36               int (*handler)(struct sockaddr_nl *,struct nlmsghdr *n, void *),
  37               void *jarg)
  38 .sp
  39 int rtnl_from_file(FILE *rtnl,
  40               int (*handler)(struct sockaddr_nl *,struct nlmsghdr *n, void *),
  41               void *jarg)
  42 .sp
  43 int addattr32(struct nlmsghdr *n, int maxlen, int type, __u32 data)
  44 .sp
  45 int addattr_l(struct nlmsghdr *n, int maxlen, int type, void *data, int alen)
  46 .sp
  47 int rta_addattr32(struct rtattr *rta, int maxlen, int type, __u32 data)
  48 .sp
  49 int rta_addattr_l(struct rtattr *rta, int maxlen, int type, void *data, int alen)
  50 .SH DESCRIPTION
  51 libnetlink provides a higher level interface to
  52 .BR rtnetlink(7).
  53 The read functions return 0 on success and a negative errno on failure.
  54 The send functions return the amount of data sent, or -1 on error.
  55 .TP
  56 rtnl_open
  57 Open a rtnetlink socket and save the state into the
  58 .B rth
  59 handle. This handle is passed to all subsequent calls.
  60 .B subscriptions
  61 is a bitmap of the rtnetlink multicast groups the socket will be
  62 a member of.
  63
  64 .TP
  65 rtnl_wilddump_request
  66 Request a full dump of the
  67 .B type
  68 database for
  69 .B family
  70 addresses.
  71 .B type
  72 is a rtnetlink message type.
  73 .\" XXX
  74
  75 .TP
  76 rtnl_dump_request
  77 Request a full dump of the
  78 .B type
  79 data buffer into
  80 .B buf
  81 with maximum length of
  82 .B len.
  83 .B type
  84 is a rtnetlink message type.
  85
  86 .TP
  87 rtnl_dump_filter
  88 Receive netlink data after a request and filter it.
  89 The
  90 .B filter
  91 callback checks if the received message is wanted. It gets the source
  92 address of the message, the message itself and
  93 .B arg1
  94 as arguments. 0 as return means that the filter passed, a negative
  95 value is returned
  96 by
  97 .I rtnl_dump_filter
  98 in case of error. NULL for
  99 .I filter
 100 means to not use a filter.
 101 .B junk
 102 is used to filter messages not destined to the local socket.
 103 Only one message bundle is received. Unless there is no message
 104 pending, this function does not block.
 105
 106 .TP
 107 rtnl_listen
 108 Receive netlink data after a request and pass it to
 109 .I handler.
 110 .B handler
 111 is a callback that gets the message source address, the message itself,
 112 and the
 113 .B jarg
 114 cookie as arguments. It will get called for all received messages.
 115 Only one message bundle is received. Unless there is no message
 116 pending this function does not block.
 117
 118 .TP
 119 rtnl_from_file
 120 Works like
 121 .I rtnl_listen,
 122 but reads a netlink message bundle from the file
 123 .B file
 124 and passes the messages to
 125 .B handler
 126 for parsing. The file contains raw data as received from a rtnetlink socket.
 127 .PP
 128 The following functions are useful to construct custom rtnetlink messages. For
 129 simple database dumping with filtering it is better to use the higher level
 130 functions above. See
 131 .BR rtnetlink(3)
 132 and
 133 .BR netlink(3)
 134 on how to generate a rtnetlink message. The following utility functions
 135 require a continuous buffer that already contains a netlink message header
 136 and a rtnetlink request.
 137
 138 .TP
 139 rtnl_send
 140 Send the rtnetlink message in
 141 .B buf
 142 of length
 143 .B len
 144 to handle
 145 .B rth.
 146
 147 .TP
 148 addattr32
 149 Add a __u32 attribute of type
 150 .B type
 151 and with value
 152 .B data
 153 to netlink message
 154 .B n,
 155 which is part of a buffer of length
 156 .B maxlen.
 157
 158 .TP
 159 addattr_l
 160 Add a variable length attribute of type
 161 .B type
 162 and with value
 163 .B data
 164 and
 165 .B alen
 166 length to netlink message
 167 .B n,
 168 which is part of a buffer of length
 169 .B maxlen.
 170 .B data
 171 is copied.
 172
 173 .TP
 174 rta_addattr32
 175 Initialize the rtnetlink attribute
 176 .B rta
 177 with a __u32 data value.
 178
 179 .TP
 180 rta_addattr32
 181 Initialize the rtnetlink attribute
 182 .B rta
 183 with a variable length data value.
 184
 185 .SH BUGS
 186 The functions sometimes use fprintf and exit when a fatal error occurs.
 187 This library should be named librtnetlink.
 188
 189 .SH AUTHORS
 190 netlink/rtnetlink was designed and writen by Alexey Kuznetsov.
 191 Andi Kleen wrote the man page.
 192
 193 .SH SEE ALSO
 194 .BR netlink(7),
 195 .BR rtnetlink(7)
 196 .br
 197 /usr/include/linux/rtnetlink.h