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 /*
  27  * Use this as a good size to allocate generic netlink messages
  28  */
  29 #ifndef PAGE_SIZE
  30 #define PAGE_SIZE 4096
  31 #endif
  32 #define NLMSG_GOOD_SIZE (2*PAGE_SIZE)
  33 #define NLMSG_TAIL(nmsg) ((struct rtattr *) (((void *) (nmsg)) + NLMSG_ALIGN((nmsg)->nlmsg_len)))
  34 #define NLA_DATA(na) ((void *)((char*)(na) + NLA_HDRLEN))
  35 #define NLA_NEXT_ATTR(attr) ((void *)((char *)attr) + NLA_ALIGN(attr->nla_len))
  36
  37 /*
  38  * struct nl_handler : the handler for netlink sockets, this structure
  39  *  is used all along the netlink socket life cycle to specify the
  40  *  netlink socket to be used.
  41  *
  42  * @fd: the file descriptor of the netlink socket
  43  * @seq: the sequence number of the netlink messages
  44  * @local: the bind address
  45  * @peer: the peer address
  46  */
  47 struct nl_handler {
  48         int fd;
  49         int seq;
  50         struct sockaddr_nl local;
  51         struct sockaddr_nl peer;
  52 };
  53
  54 /*
  55  * struct nlmsg : the netlink message structure. This message is to be used to
  56  *  be allocated with netlink_alloc.
  57  *
  58  * @nlmsghdr: a pointer to a netlink message header
  59  * @cap: capacity of the netlink message, this is the initially allocated size
  60  *              and later operations (e.g. reserve and put) can not exceed this limit.
  61  */
  62 struct nlmsg {
  63         struct nlmsghdr *nlmsghdr;
  64         ssize_t cap;
  65 };
  66
  67 /*
  68  * netlink_open : open a netlink socket, the function will
  69  *  fill the handler with the right value
  70  *
  71  * @handler: a netlink handler to be used all along the netlink
  72  *  socket life cycle
  73  * @protocol: specify the protocol to be used when opening the
  74  *  netlink socket
  75  *
  76  * Return 0 on success, < 0 otherwise
  77  */
  78 int netlink_open(struct nl_handler *handler, int protocol);
  79
  80 /*
  81  * netlink_close : close a netlink socket, after this call,
  82  *  the handler is no longer valid
  83  *
  84  * @handler: a handler to the netlink socket
  85  *
  86  * Returns 0 on success, < 0 otherwise
  87  */
  88 int netlink_close(struct nl_handler *handler);
  89
  90 /*
  91  * netlink_rcv : receive a netlink message from the kernel.
  92  *  It is up to the caller to manage the allocation of the
  93  *  netlink message
  94  *
  95  * @handler: a handler to the netlink socket
  96  * @nlmsg: a netlink message
  97  *
  98  * Returns 0 on success, < 0 otherwise
  99  */
 100 int netlink_rcv(struct nl_handler *handler, struct nlmsg *nlmsg);
 101
 102 /*
 103  * netlink_send: send a netlink message to the kernel. It is up
 104  *  to the caller to manage the allocate of the netlink message
 105  *
 106  * @handler: a handler to the netlink socket
 107  * @nlmsg: a netlink message
 108  *
 109  * Returns 0 on success, < 0 otherwise
 110  */
 111 int netlink_send(struct nl_handler *handler, struct nlmsg *nlmsg);
 112
 113 /*
 114  * netlink_transaction: send a request to the kernel and read the response.
 115  *  This is useful for transactional protocol. It is up to the caller
 116  *  to manage the allocation of the netlink message.
 117  *
 118  * @handler: a handler to a opened netlink socket
 119  * @request: a netlink message pointer containing the request
 120  * @answer: a netlink message pointer to receive the result
 121  *
 122  * Returns 0 on success, < 0 otherwise
 123  */
 124 int netlink_transaction(struct nl_handler *handler,
 125                         struct nlmsg *request, struct nlmsg *anwser);
 126
 127 /*
 128  * nla_put_string: copy a null terminated string to a netlink message
 129  *  attribute
 130  *
 131  * @nlmsg: the netlink message to be filled
 132  * @attr: the attribute name of the string
 133  * @string: a null terminated string to be copied to the netlink message
 134  *
 135  * Returns 0 on success, < 0 otherwise
 136  */
 137 int nla_put_string(struct nlmsg *nlmsg, int attr, const char *string);
 138
 139 /*
 140  * nla_put_buffer: copy a buffer with a specified size to a netlink
 141  * message attribute
 142  *
 143  * @nlmsg: the netlink message to be filled
 144  * @attr: the attribute name of the string
 145  * @data: a pointer to a buffer
 146  * @size: the size of the buffer
 147  *
 148  * Returns 0 on success, < 0 otherwise
 149  */
 150 int nla_put_buffer(struct nlmsg *nlmsg, int attr,
 151                    const void *data, size_t size);
 152
 153 /*
 154  * nla_put_u32: copy an integer to a netlink message attribute
 155  *
 156  * @nlmsg: the netlink message to be filled
 157  * @attr: the attribute name of the integer
 158  * @string: an integer  to be copied to the netlink message
 159  *
 160  * Returns 0 on success, < 0 otherwise
 161  */
 162 int nla_put_u32(struct nlmsg *nlmsg, int attr, int value);
 163
 164 /*
 165  * nla_put_u16: copy an integer to a netlink message attribute
 166  *
 167  * @nlmsg: the netlink message to be filled
 168  * @attr: the attribute name of the unsigned 16-bit value
 169  * @value: 16-bit attribute data value to be copied to the netlink message
 170  *
 171  * Returns 0 on success, < 0 otherwise
 172  */
 173 int nla_put_u16(struct nlmsg *nlmsg, int attr, unsigned short value);
 174
 175 /*
 176  * nla_put_attr: add an attribute name to a netlink
 177  *
 178  * @nlmsg: the netlink message to be filled
 179  * @attr: the attribute name of the integer
 180  *
 181  * Returns 0 on success, < 0 otherwise
 182  */
 183 int nla_put_attr(struct nlmsg *nlmsg, int attr);
 184
 185 /*
 186  * nla_begin_nested: begin the nesting attribute
 187  *
 188  * @nlmsg: the netlink message to be filled
 189  * @attr: the netsted attribute name
 190  *
 191  * Returns current nested pointer to be reused
 192  * to nla_end_nested.
 193  */
 194 struct rtattr *nla_begin_nested(struct nlmsg *nlmsg, int attr);
 195
 196 /*
 197  * nla_end_nested: end the nesting attribute
 198  *
 199  * @nlmsg: the netlink message
 200  * @nested: the nested pointer
 201  *
 202  * Returns the current
 203  */
 204 void nla_end_nested(struct nlmsg *nlmsg, struct rtattr *attr);
 205
 206 /*
 207  * nlmsg_allocate : allocate a netlink message. The netlink format message
 208  *  is a header, a padding, a payload and a padding again.
 209  *  When a netlink message is allocated, the size specify the
 210  *  payload we want. So the real size of the allocated message
 211  *  is sizeof(header) + sizeof(padding) + payloadsize + sizeof(padding),
 212  *  in other words, the function will allocate more than specified. When
 213  *  the buffer is allocated, the content is zeroed.
 214  *  The function will also fill the field nlmsg_len with NLMSG_HDRLEN.
 215  *  If the allocation must be for the specified size, just use malloc.
 216  *
 217  * @size: the capacity of the payload to be allocated
 218  *
 219  * Returns a pointer to the newly allocated netlink message, NULL otherwise
 220  */
 221 struct nlmsg *nlmsg_alloc(size_t size);
 222
 223 /*
 224  * nlmsg_alloc_reserve: like nlmsg_alloc(), but reserve the whole payload
 225  *  after allocated, that is, the field nlmsg_len be set to the capacity
 226  *  of nlmsg. Often used to allocate a message for the reply.
 227  *
 228  * @size: the capacity of the payload to be allocated.
 229  */
 230 struct nlmsg *nlmsg_alloc_reserve(size_t size);
 231
 232 /*
 233  * Reserve room for additional data at the tail of a netlink message
 234  *
 235  * @nlmsg: the netlink message
 236  * @len: length of additional data to reserve room for
 237  *
 238  * Returns a pointer to newly reserved room or NULL
 239  */
 240 void *nlmsg_reserve(struct nlmsg *nlmsg, size_t len);
 241
 242 /*
 243  * nlmsg_free : free a previously allocate message
 244  *
 245  * @nlmsg: the netlink message to be freed
 246  */
 247 void nlmsg_free(struct nlmsg *nlmsg);
 248
 249 /*
 250  * nlmsg_data : returns a pointer to the data contained in the netlink message
 251  *
 252  * @nlmsg : the netlink message to get the data
 253  *
 254  * Returns a pointer to the netlink data or NULL if there is no data
 255  */
 256 void *nlmsg_data(struct nlmsg *nlmsg);
 257
 258
 259 #endif