src/lxc/nl.h

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