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