api: in constructor function calls, always put the returned object pointer first (or second)

Previously the returned object of constructor functions where sometimes
returned as last, sometimes as first and sometimes as second parameter.
Let's clean this up a bit. Here are the new rules:

1. The object the new object is derived from is put first, if there is any

2. The object we are creating will be returned in the next arguments

3. This is followed by any additional arguments

Rationale:

For functions that operate on an object we always put that object first.
Constructors should probably not be too different in this regard. Also,
if the additional parameters might want to use varargs which suggests to
put them last.

Note that this new scheme only applies to constructor functions, not to
all other functions. We do give a lot of freedom for those.

Note that this commit only changes the order of the new functions we
added, for old ones we accept the wrong order and leave it like that.

6 files changed, 26 insertions, 27 deletions

diff --git a/src/systemd/sd-bus.h b/src/systemd/sd-bus.h
index 94a435ac6d..0629e47dea 100644
--- a/src/systemd/sd-bus.h
+++ b/src/systemd/sd-bus.h
@@ -177,12 +177,12 @@ int sd_bus_remove_object_manager(sd_bus *bus, const char *path);
 
 /* Message object */
 
-int sd_bus_message_new_signal(sd_bus *bus, const char *path, const char *interface, const char *member, sd_bus_message **m);
-int sd_bus_message_new_method_call(sd_bus *bus, const char *destination, const char *path, const char *interface, const char *member, sd_bus_message **m);
+int sd_bus_message_new_signal(sd_bus *bus, sd_bus_message **m, const char *path, const char *interface, const char *member);
+int sd_bus_message_new_method_call(sd_bus *bus, sd_bus_message **m, const char *destination, const char *path, const char *interface, const char *member);
 int sd_bus_message_new_method_return(sd_bus_message *call, sd_bus_message **m);
-int sd_bus_message_new_method_error(sd_bus_message *call, const sd_bus_error *e, sd_bus_message **m);
+int sd_bus_message_new_method_error(sd_bus_message *call, sd_bus_message **m, const sd_bus_error *e);
 int sd_bus_message_new_method_errorf(sd_bus_message *call, sd_bus_message **m, const char *name, const char *format, ...) _sd_printf_(4, 5);
-int sd_bus_message_new_method_errno(sd_bus_message *call, int error, const sd_bus_error *e, sd_bus_message **m);
+int sd_bus_message_new_method_errno(sd_bus_message *call, sd_bus_message **m, int error, const sd_bus_error *e);
 int sd_bus_message_new_method_errnof(sd_bus_message *call, sd_bus_message **m, int error, const char *format, ...) _sd_printf_(4, 5);
 
 sd_bus_message* sd_bus_message_ref(sd_bus_message *m);
@@ -284,7 +284,7 @@ int sd_bus_query_sender_creds(sd_bus_message *call, uint64_t mask, sd_bus_creds
 
 /* Credential handling */
 
-int sd_bus_creds_new_from_pid(pid_t pid, uint64_t creds_mask, sd_bus_creds **ret);
+int sd_bus_creds_new_from_pid(sd_bus_creds **ret, pid_t pid, uint64_t creds_mask);
 sd_bus_creds *sd_bus_creds_ref(sd_bus_creds *c);
 sd_bus_creds *sd_bus_creds_unref(sd_bus_creds *c);
 uint64_t sd_bus_creds_get_mask(const sd_bus_creds *c);
diff --git a/src/systemd/sd-event.h b/src/systemd/sd-event.h
index b911485671..68c52c5145 100644
--- a/src/systemd/sd-event.h
+++ b/src/systemd/sd-event.h
@@ -76,13 +76,13 @@ int sd_event_new(sd_event **e);
 sd_event* sd_event_ref(sd_event *e);
 sd_event* sd_event_unref(sd_event *e);
 
-int sd_event_add_io(sd_event *e, int fd, uint32_t events, sd_event_io_handler_t callback, void *userdata, sd_event_source **s);
-int sd_event_add_monotonic(sd_event *e, uint64_t usec, uint64_t accuracy, sd_event_time_handler_t callback, void *userdata, sd_event_source **s);
-int sd_event_add_realtime(sd_event *e, uint64_t usec, uint64_t accuracy, sd_event_time_handler_t callback, void *userdata, sd_event_source **s);
-int sd_event_add_signal(sd_event *e, int sig, sd_event_signal_handler_t callback, void *userdata, sd_event_source **s);
-int sd_event_add_child(sd_event *e, pid_t pid, int options, sd_event_child_handler_t callback, void *userdata, sd_event_source **s);
-int sd_event_add_defer(sd_event *e, sd_event_handler_t callback, void *userdata, sd_event_source **s);
-int sd_event_add_exit(sd_event *e, sd_event_handler_t callback, void *userdata, sd_event_source **s);
+int sd_event_add_io(sd_event *e, sd_event_source **s, int fd, uint32_t events, sd_event_io_handler_t callback, void *userdata);
+int sd_event_add_monotonic(sd_event *e, sd_event_source **s, uint64_t usec, uint64_t accuracy, sd_event_time_handler_t callback, void *userdata);
+int sd_event_add_realtime(sd_event *e, sd_event_source **s, uint64_t usec, uint64_t accuracy, sd_event_time_handler_t callback, void *userdata);
+int sd_event_add_signal(sd_event *e, sd_event_source **s, int sig, sd_event_signal_handler_t callback, void *userdata);
+int sd_event_add_child(sd_event *e, sd_event_source **s, pid_t pid, int options, sd_event_child_handler_t callback, void *userdata);
+int sd_event_add_defer(sd_event *e, sd_event_source **s, sd_event_handler_t callback, void *userdata);
+int sd_event_add_exit(sd_event *e, sd_event_source **s, sd_event_handler_t callback, void *userdata);
 
 int sd_event_run(sd_event *e, uint64_t timeout);
 int sd_event_loop(sd_event *e);
diff --git a/src/systemd/sd-journal.h b/src/systemd/sd-journal.h
index cdd7c14a57..eb24372359 100644
--- a/src/systemd/sd-journal.h
+++ b/src/systemd/sd-journal.h
@@ -136,7 +136,7 @@ int sd_journal_wait(sd_journal *j, uint64_t timeout_usec);
 int sd_journal_reliable_fd(sd_journal *j);
 
 int sd_journal_get_catalog(sd_journal *j, char **text);
-int sd_journal_get_catalog_for_message_id(sd_id128_t id, char **ret);
+int sd_journal_get_catalog_for_message_id(sd_id128_t id, char **text);
 
 #define SD_JOURNAL_FOREACH(j)                                           \
         if (sd_journal_seek_head(j) >= 0)                               \
diff --git a/src/systemd/sd-memfd.h b/src/systemd/sd-memfd.h
index 76cb8751cc..753ed68cd8 100644
--- a/src/systemd/sd-memfd.h
+++ b/src/systemd/sd-memfd.h
@@ -32,9 +32,9 @@ _SD_BEGIN_DECLARATIONS;
 
 typedef struct sd_memfd sd_memfd;
 
-int sd_memfd_new(const char *name, sd_memfd **m);
-int sd_memfd_new_and_map(const char *name, sd_memfd **m, size_t sz, void **p);
-int sd_memfd_make(int fd, sd_memfd **m);
+int sd_memfd_new(sd_memfd **m, const char *name);
+int sd_memfd_new_from_fd(sd_memfd **m, int fd);
+int sd_memfd_new_and_map(sd_memfd **m, const char *name, size_t sz, void **p);
 
 void sd_memfd_free(sd_memfd *m);
 
diff --git a/src/systemd/sd-resolve.h b/src/systemd/sd-resolve.h
index 14f45573b0..df69e4b809 100644
--- a/src/systemd/sd-resolve.h
+++ b/src/systemd/sd-resolve.h
@@ -68,7 +68,7 @@ int sd_resolve_wait(sd_resolve *resolve, uint64_t timeout_usec);
  * getaddrinfo(3). The function returns a new query object. When the
  * query is completed you may retrieve the results using
  * sd_resolve_getaddrinfo_done(). */
-int sd_resolve_getaddrinfo(sd_resolve *resolve, const char *node, const char *service, const struct addrinfo *hints, sd_resolve_query **q);
+int sd_resolve_getaddrinfo(sd_resolve *resolve, sd_resolve_query **q, const char *node, const char *service, const struct addrinfo *hints);
 
 /** Retrieve the results of a preceding sd_resolve_getaddrinfo()
  * call. Returns a addrinfo structure and a return value compatible
@@ -90,7 +90,7 @@ void sd_resolve_freeaddrinfo(struct addrinfo *ai);
  * query is completed you may retrieve the results using
  * sd_resolve_getnameinfo_done(). Set gethost (resp. getserv) to non-zero
  * if you want to query the hostname (resp. the service name). */
-int sd_resolve_getnameinfo(sd_resolve *resolve, const struct sockaddr *sa, socklen_t salen, int flags, int gethost, int getserv, sd_resolve_query **q);
+int sd_resolve_getnameinfo(sd_resolve *resolve, sd_resolve_query **q, const struct sockaddr *sa, socklen_t salen, int flags, int gethost, int getserv);
 
 /** Retrieve the results of a preceding sd_resolve_getnameinfo()
  * call. Returns the hostname and the service name in ret_host and
@@ -103,13 +103,13 @@ int sd_resolve_getnameinfo_done(sd_resolve_query* q, char **ret_host, char **ret
  * compatible with the ones of libc's res_query(3). The function returns a new
  * query object. When the query is completed you may retrieve the results using
  * sd_resolve_res_done().  */
-int sd_resolve_res_query(sd_resolve *resolve, const char *dname, int class, int type, sd_resolve_query **q);
+int sd_resolve_res_query(sd_resolve *resolve, sd_resolve_query **q, const char *dname, int class, int type);
 
 /** Issue an resolver query on the specified session. The arguments are
  * compatible with the ones of libc's res_search(3). The function returns a new
  * query object. When the query is completed you may retrieve the results using
  * sd_resolve_res_done().  */
-int sd_resolve_res_search(sd_resolve *resolve, const char *dname, int class, int type, sd_resolve_query **q);
+int sd_resolve_res_search(sd_resolve *resolve, sd_resolve_query **q, const char *dname, int class, int type);
 
 /** Retrieve the results of a preceding sd_resolve_res_query() or
  * resolve_res_search call.  The query object q is destroyed by this
diff --git a/src/systemd/sd-rtnl.h b/src/systemd/sd-rtnl.h
index 502183e9e8..f2b3a53fd6 100644
--- a/src/systemd/sd-rtnl.h
+++ b/src/systemd/sd-rtnl.h
@@ -40,7 +40,7 @@ typedef struct sd_rtnl_message sd_rtnl_message;
 typedef int (*sd_rtnl_message_handler_t)(sd_rtnl *rtnl, sd_rtnl_message *m, void *userdata);
 
 /* bus */
-int sd_rtnl_open(uint32_t groups, sd_rtnl **nl);
+int sd_rtnl_open(sd_rtnl **nl, uint32_t groups);
 
 sd_rtnl *sd_rtnl_ref(sd_rtnl *nl);
 sd_rtnl *sd_rtnl_unref(sd_rtnl *nl);
@@ -67,12 +67,11 @@ int sd_rtnl_attach_event(sd_rtnl *nl, sd_event *e, int priority);
 int sd_rtnl_detach_event(sd_rtnl *nl);
 
 /* messages */
-int sd_rtnl_message_new_link(sd_rtnl *rtnl, uint16_t msg_type, int index,
-                             sd_rtnl_message **ret);
-int sd_rtnl_message_new_addr(sd_rtnl *rtnl, uint16_t msg_type, int index,
-                             unsigned char family, sd_rtnl_message **ret);
-int sd_rtnl_message_new_route(sd_rtnl *rtnl, uint16_t nlmsg_type,
-                              unsigned char rtm_family, sd_rtnl_message **ret);
+int sd_rtnl_message_new_link(sd_rtnl *rtnl, sd_rtnl_message **ret, uint16_t msg_type, int index);
+int sd_rtnl_message_new_addr(sd_rtnl *rtnl, sd_rtnl_message **ret, uint16_t msg_type, int index,
+                             unsigned char family);
+int sd_rtnl_message_new_route(sd_rtnl *rtnl, sd_rtnl_message **ret, uint16_t nlmsg_type,
+                              unsigned char rtm_family);
 
 sd_rtnl_message *sd_rtnl_message_ref(sd_rtnl_message *m);
 sd_rtnl_message *sd_rtnl_message_unref(sd_rtnl_message *m);