[Libguestfs] [PATCH libnbd v2 3/4] generator: Document non-NULL behaviour of some parameters

In the C API documentation mention the potential problems of calling non-nullable parameters with NULL. Usually an error is returned, but warnings and worse might happen too. Thanks: Eric Blake --- docs/libnbd.pod | 18 ++++++++++++++++++ generator/C.ml | 21 +++++++++++++++++++++ 2 files changed, 39 insertions(+) diff --git a/docs/libnbd.pod b/docs/libnbd.pod index eae9bb413b..170fc1fa07 100644 --- a/docs/libnbd.pod +++ b/docs/libnbd.pod @@ -387,8 +387,26 @@ The library ran out of memory while performing some operation. A request is too large, for example if you try to read too many bytes in a single L<nbd_pread(3)> call. +=item C<EFAULT> + +A pointer parameter was C<NULL> when it should be non-NULL. +See the section below. + =back +=head2 Non-NULL parameters + +Almost all libnbd functions when called from C take one or more +pointer parameters that must not be C<NULL>. For example, the handle +parameter, strings and buffers should usually not be C<NULL>. + +If a C<NULL> is passed as one of these parameters, libnbd attempts to +return an error with L<nbd_get_errno(3)> returning C<EFAULT>. + +However it may cause other compiler-related warnings and even +undefined behaviour, so you should try to avoid this programming +mistake. + =head1 DEBUGGING MESSAGES Libnbd can print lots of debugging messages, useful if you have a diff --git a/generator/C.ml b/generator/C.ml index bfc216609e..dc123d20a4 100644 --- a/generator/C.ml +++ b/generator/C.ml @@ -107,6 +107,11 @@ let | UInt64 n -> [n] | UIntPtr n -> [n] +let name_of_optarg = + function + | OClosure { cbname } -> cbname + | OFlags (n, _, _) -> n + let arg_attr_nonnull = function (* BytesIn/Out are passed using a non-null pointer, and size_t *) @@ -974,6 +979,7 @@ let pr "=head1 ERRORS\n"; pr "\n"; + if may_set_error then ( let value = match errcode with | Some value -> value @@ -987,6 +993,21 @@ let pr "This function does not fail.\n"; pr "\n"; + pr "The following parameters must not be NULL: C<h>"; + List.iter ( + fun arg -> + let nns = arg_attr_nonnull arg in + if List.mem true nns then pr ", C<%s>" (List.hd (name_of_arg arg)) + ) args; + List.iter ( + fun arg -> + let nns = optarg_attr_nonnull arg in + if List.mem true nns then pr ", C<%s>" (name_of_optarg arg) + ) optargs; + pr ".\n"; + pr "For more information see L<libnbd(3)/Non-NULL parameters>.\n"; + pr "\n"; + if permitted_states <> [] then ( pr "=head1 HANDLE STATE\n"; pr "\n"; -- 2.37.0.rc2