[PATCH 0/1] Libibumad: Clarify the man page for function umad_get_ca_portguids

[PATCH 0/1] Libibumad: Clarify the man page for function umad_get_ca_portguids

[jay.p.patel-ral2JQCrhuEAvxtiuMwx3w]

From: Jay Patel <jay.p.patel-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>

The function umad_get_ca_portguids returns a value of 2 even if there is
only one valid port. The man page for the function only specifies that the
return value is equal to number of port GUIDs actually filled. This may be
confusing for user as it does not specify that there may be invalid entries
in the array.

Any change in interface may break existing user. Hence, clarification is
made in man page that some entries in the array may be invalid and should
be ignored.

Jay Patel (1):
  Libibumad: Clarify the man page for function umad_get_ca_portguids

 man/umad_get_ca_portguids.3 | 3 +++
 1 file changed, 3 insertions(+)

-- 
1.8.2.3

--
To unsubscribe from this list: send the line "unsubscribe linux-rdma" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 1/1] Libibumad: Clarify the man page for function umad_get_ca_portguids

[jay.p.patel-ral2JQCrhuEAvxtiuMwx3w]

From: Jay Patel <jay.p.patel-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>

Clarified the return value explanation of umad_get_ca_portguids() in
corresponding man page.

Signed-off-by: Jay Patel <jay.p.patel-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
---
 man/umad_get_ca_portguids.3 | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/man/umad_get_ca_portguids.3 b/man/umad_get_ca_portguids.3
index 3512649..ff8d433 100644
--- a/man/umad_get_ca_portguids.3
+++ b/man/umad_get_ca_portguids.3
@@ -29,6 +29,9 @@ uint64_t entries.
 On success,
 .B umad_get_ca_portguids()
 returns a non-negative value equal to the number of port GUIDs actually filled.
+Not all filled entries may be valid. Invalid entries will be 0.
+For example, calling function on computing node with only one port returns a value of 2.
+The value at index zero will be invalid as it is reserved for switches.
 On failure, a negative value is returned.
 .SH "SEE ALSO"
 .BR umad_get_cas_names (3)
-- 
1.8.2.3

--
To unsubscribe from this list: send the line "unsubscribe linux-rdma" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/1] Libibumad: Clarify the man page for function umad_get_ca_portguids

[Hal Rosenstock]

On 8/8/2016 1:49 PM, jay.p.patel-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org wrote:
> From: Jay Patel <jay.p.patel-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> 
> Clarified the return value explanation of umad_get_ca_portguids() in
> corresponding man page.

Thanks. Applied.

> Signed-off-by: Jay Patel <jay.p.patel-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> ---
>  man/umad_get_ca_portguids.3 | 3 +++
>  1 file changed, 3 insertions(+)
> 
> diff --git a/man/umad_get_ca_portguids.3 b/man/umad_get_ca_portguids.3
> index 3512649..ff8d433 100644
> --- a/man/umad_get_ca_portguids.3
> +++ b/man/umad_get_ca_portguids.3
> @@ -29,6 +29,9 @@ uint64_t entries.
>  On success,
>  .B umad_get_ca_portguids()
>  returns a non-negative value equal to the number of port GUIDs actually filled.
> +Not all filled entries may be valid. Invalid entries will be 0.
> +For example, calling function on computing node with only one port returns a value of 2.
> +The value at index zero will be invalid as it is reserved for switches.

I changed the wording a little.

-- Hal

>  On failure, a negative value is returned.
>  .SH "SEE ALSO"
>  .BR umad_get_cas_names (3)
> 
--
To unsubscribe from this list: send the line "unsubscribe linux-rdma" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html