src/lxc/nl.h

   1 /*
   2  * lxc: linux Container library
   3  *
   4  * (C) Copyright IBM Corp. 2007, 2008
   5  *
   6  * Authors:
   7  * Daniel Lezcano <daniel.lezcano at free.fr>
   8  *
   9  * This library is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public
  11  * License as published by the Free Software Foundation; either
  12  * version 2.1 of the License, or (at your option) any later version.
  13  *
  14  * This library is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with this library; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  22  */
  23 #ifndef __LXC_NL_H
  24 #define __LXC_NL_H
  25
  26 #include <stdio.h>
  27
  28 /*
  29  * Use this as a good size to allocate generic netlink messages
  30  */
  31 #ifndef PAGE_SIZE
  32 #define PAGE_SIZE 4096
  33 #endif
  34 #define NLMSG_GOOD_SIZE (2*PAGE_SIZE)
  35 #define NLMSG_TAIL(nmsg) ((struct rtattr *) (((void *) (nmsg)) + NLMSG_ALIGN((nmsg)->nlmsg_len)))
  36 #define NLA_DATA(na) ((void *)((char*)(na) + NLA_HDRLEN))
  37 #define NLA_NEXT_ATTR(attr) ((void *)((char *)attr) + NLA_ALIGN(attr->nla_len))
  38
  39 /*
  40  * struct nl_handler : the handler for netlink sockets, this structure
  41  *  is used all along the netlink socket life cycle to specify the
  42  *  netlink socket to be used.
  43  *
  44  * @fd: the file descriptor of the netlink socket
  45  * @seq: the sequence number of the netlink messages
  46  * @local: the bind address
  47  * @peer: the peer address
  48  */
  49 struct nl_handler {
  50         int fd;
  51         int seq;
  52         struct sockaddr_nl local;
  53         struct sockaddr_nl peer;
  54 };
  55
  56 /*
  57  * struct nlmsg : the netlink message structure. This message is to be used to
  58  *  be allocated with netlink_alloc.
  59  *
  60  * @nlmsghdr: a pointer to a netlink message header
  61  * @cap: capacity of the netlink message, this is the initially allocated size
  62  *              and later operations (e.g. reserve and put) can not exceed this limit.
  63  */
  64 struct nlmsg {
  65         struct nlmsghdr *nlmsghdr;
  66         ssize_t cap;
  67 };
  68
  69 /*
  70  * netlink_open : open a netlink socket, the function will
  71  *  fill the handler with the right value
  72  *
  73  * @handler: a netlink handler to be used all along the netlink
  74  *  socket life cycle
  75  * @protocol: specify the protocol to be used when opening the
  76  *  netlink socket
  77  *
  78  * Return 0 on success, < 0 otherwise
  79  */
  80 int netlink_open(struct nl_handler *handler, int protocol);
  81
  82 /*
  83  * netlink_close : close a netlink socket, after this call,
  84  *  the handler is no longer valid
  85  *
  86  * @handler: a handler to the netlink socket
  87  *
  88  * Returns 0 on success, < 0 otherwise
  89  */
  90 int netlink_close(struct nl_handler *handler);
  91
  92 /*
  93  * netlink_rcv : receive a netlink message from the kernel.
  94  *  It is up to the caller to manage the allocation of the
  95  *  netlink message
  96  *
  97  * @handler: a handler to the netlink socket
  98  * @nlmsg: a netlink message
  99  *
 100  * Returns 0 on success, < 0 otherwise
 101  */
 102 int netlink_rcv(struct nl_handler *handler, struct nlmsg *nlmsg);
 103 int __netlink_recv(struct nl_handler *handler, struct nlmsghdr *nlmsg);
 104
 105 /*
 106  * netlink_send: send a netlink message to the kernel. It is up
 107  *  to the caller to manage the allocate of the netlink message
 108  *
 109  * @handler: a handler to the netlink socket
 110  * @nlmsg: a netlink message
 111  *
 112  * Returns 0 on success, < 0 otherwise
 113  */
 114 int netlink_send(struct nl_handler *handler, struct nlmsg *nlmsg);
 115 int __netlink_send(struct nl_handler *handler, struct nlmsghdr *nlmsg);
 116
 117 /*
 118  * netlink_transaction: send a request to the kernel and read the response.
 119  *  This is useful for transactional protocol. It is up to the caller
 120  *  to manage the allocation of the netlink message.
 121  *
 122  * @handler: a handler to a opened netlink socket
 123  * @request: a netlink message pointer containing the request
 124  * @answer: a netlink message pointer to receive the result
 125  *
 126  * Returns 0 on success, < 0 otherwise
 127  */
 128 int netlink_transaction(struct nl_handler *handler,
 129                         struct nlmsg *request, struct nlmsg *answer);
 130 int __netlink_transaction(struct nl_handler *handler, struct nlmsghdr *request,
 131                           struct nlmsghdr *answer);
 132
 133 /*
 134  * nla_put_string: copy a null terminated string to a netlink message
 135  *  attribute
 136  *
 137  * @nlmsg: the netlink message to be filled
 138  * @attr: the attribute name of the string
 139  * @string: a null terminated string to be copied to the netlink message
 140  *
 141  * Returns 0 on success, < 0 otherwise
 142  */
 143 int nla_put_string(struct nlmsg *nlmsg, int attr, const char *string);
 144
 145 /*
 146  * nla_put_buffer: copy a buffer with a specified size to a netlink
 147  * message attribute
 148  *
 149  * @nlmsg: the netlink message to be filled
 150  * @attr: the attribute name of the string
 151  * @data: a pointer to a buffer
 152  * @size: the size of the buffer
 153  *
 154  * Returns 0 on success, < 0 otherwise
 155  */
 156 int nla_put_buffer(struct nlmsg *nlmsg, int attr,
 157                    const void *data, size_t size);
 158
 159 /*
 160  * nla_put_u32: copy an integer to a netlink message attribute
 161  *
 162  * @nlmsg: the netlink message to be filled
 163  * @attr: the attribute name of the integer
 164  * @string: an integer  to be copied to the netlink message
 165  *
 166  * Returns 0 on success, < 0 otherwise
 167  */
 168 int nla_put_u32(struct nlmsg *nlmsg, int attr, int value);
 169
 170 /*
 171  * nla_put_u16: copy an integer to a netlink message attribute
 172  *
 173  * @nlmsg: the netlink message to be filled
 174  * @attr: the attribute name of the unsigned 16-bit value
 175  * @value: 16-bit attribute data value to be copied to the netlink message
 176  *
 177  * Returns 0 on success, < 0 otherwise
 178  */
 179 int nla_put_u16(struct nlmsg *nlmsg, int attr, unsigned short value);
 180
 181 /*
 182  * nla_put_attr: add an attribute name to a netlink
 183  *
 184  * @nlmsg: the netlink message to be filled
 185  * @attr: the attribute name of the integer
 186  *
 187  * Returns 0 on success, < 0 otherwise
 188  */
 189 int nla_put_attr(struct nlmsg *nlmsg, int attr);
 190
 191 /*
 192  * nla_begin_nested: begin the nesting attribute
 193  *
 194  * @nlmsg: the netlink message to be filled
 195  * @attr: the netsted attribute name
 196  *
 197  * Returns current nested pointer to be reused
 198  * to nla_end_nested.
 199  */
 200 struct rtattr *nla_begin_nested(struct nlmsg *nlmsg, int attr);
 201
 202 /*
 203  * nla_end_nested: end the nesting attribute
 204  *
 205  * @nlmsg: the netlink message
 206  * @nested: the nested pointer
 207  *
 208  * Returns the current
 209  */
 210 void nla_end_nested(struct nlmsg *nlmsg, struct rtattr *attr);
 211
 212 /*
 213  * nlmsg_allocate : allocate a netlink message. The netlink format message
 214  *  is a header, a padding, a payload and a padding again.
 215  *  When a netlink message is allocated, the size specify the
 216  *  payload we want. So the real size of the allocated message
 217  *  is sizeof(header) + sizeof(padding) + payloadsize + sizeof(padding),
 218  *  in other words, the function will allocate more than specified. When
 219  *  the buffer is allocated, the content is zeroed.
 220  *  The function will also fill the field nlmsg_len with NLMSG_HDRLEN.
 221  *  If the allocation must be for the specified size, just use malloc.
 222  *
 223  * @size: the capacity of the payload to be allocated
 224  *
 225  * Returns a pointer to the newly allocated netlink message, NULL otherwise
 226  */
 227 struct nlmsg *nlmsg_alloc(size_t size);
 228
 229 /*
 230  * nlmsg_alloc_reserve: like nlmsg_alloc(), but reserve the whole payload
 231  *  after allocated, that is, the field nlmsg_len be set to the capacity
 232  *  of nlmsg. Often used to allocate a message for the reply.
 233  *
 234  * @size: the capacity of the payload to be allocated.
 235  */
 236 struct nlmsg *nlmsg_alloc_reserve(size_t size);
 237
 238 /*
 239  * Reserve room for additional data at the tail of a netlink message
 240  *
 241  * @nlmsg: the netlink message
 242  * @len: length of additional data to reserve room for
 243  *
 244  * Returns a pointer to newly reserved room or NULL
 245  */
 246 void *nlmsg_reserve(struct nlmsg *nlmsg, size_t len);
 247
 248 /*
 249  * nlmsg_free : free a previously allocate message
 250  *
 251  * @nlmsg: the netlink message to be freed
 252  */
 253 void nlmsg_free(struct nlmsg *nlmsg);
 254
 255 /*
 256  * nlmsg_data : returns a pointer to the data contained in the netlink message
 257  *
 258  * @nlmsg : the netlink message to get the data
 259  *
 260  * Returns a pointer to the netlink data or NULL if there is no data
 261  */
 262 void *nlmsg_data(struct nlmsg *nlmsg);
 263
 264 extern int addattr(struct nlmsghdr *n, size_t maxlen, int type,
 265                    const void *data, size_t alen);
 266
 267 #endif