Add envz_remove to the libc manual

Hi,

I was told that Ma Shimao submitted a patch to add envz_remove to the
libc manual, but the patch could not be accepted since he does not
have a copyright assignment in place.  I have been woefully behind on
libc-alpha recently and have not seen the patch or the discussion
thread.  I have also not read the man page for envz_remove, so
Alexandre Oliva asked me if I could write this independently and post
a patch.  The patch below is the result of the same - I have written
it based on the implementation in string/envz.c and Alex told me via
email that the function is AS, AC and MT-safe like envz_strip.

I assume Alex and Carlos cannot review this since they have been
tainted by the original patch (I haven't even tried to look for a link
to it since I don't want to be tainted) so someone else will have to
review this.  If there are no reviewers till the end of the week, I
will commit this since I believe there is a chance that there are no
other reviewers who haven't read that thread.

OK to commit?

Siddhesh

	* manual/string.texi (Envz Functions): Add envz_remove.

On 03/18/2015 04:29 AM, Siddhesh Poyarekar wrote:
> Hi,
> 
> I was told that Ma Shimao submitted a patch to add envz_remove to the
> libc manual, but the patch could not be accepted since he does not
> have a copyright assignment in place.  I have been woefully behind on
> libc-alpha recently and have not seen the patch or the discussion
> thread.  I have also not read the man page for envz_remove, so
> Alexandre Oliva asked me if I could write this independently and post
> a patch.  The patch below is the result of the same - I have written
> it based on the implementation in string/envz.c and Alex told me via
> email that the function is AS, AC and MT-safe like envz_strip.
> 
> I assume Alex and Carlos cannot review this since they have been
> tainted by the original patch (I haven't even tried to look for a link
> to it since I don't want to be tainted) so someone else will have to
> review this.  If there are no reviewers till the end of the week, I
> will commit this since I believe there is a chance that there are no
> other reviewers who haven't read that thread.

I can't comment on your patch, but I can give consensus or not, that
is all I can do, given that I've seen the original patch.

> OK to commit?

LGTM.

> Siddhesh
> 
> 	* manual/string.texi (Envz Functions): Add envz_remove.
> 
> diff --git a/manual/string.texi b/manual/string.texi
> index ba5a2c7..fd1b42f 100644
> --- a/manual/string.texi
> +++ b/manual/string.texi
> @@ -2788,5 +2788,13 @@ The @code{envz_strip} function removes any null entries from @var{envz},
>  updating @code{*@var{envz}} and @code{*@var{envz_len}}.
>  @end deftypefun
>  
> +@comment envz.h
> +@comment GNU
> +@deftypefun {void} envz_remove (char **@var{envz}, size_t *@var{envz_len}, const char *@var{name})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +The @code{envz_remove} function removes an entry named @var{name} from
> +@var{envz}, updating @code{*@var{envz}} and @code{*@var{envz_len}}.
> +@end deftypefun
> +
>  @c FIXME this are undocumented:
>  @c strcasecmp_l @safety{@mtsafe{}@assafe{}@acsafe{}} see strcasecmp
> 

Cheers,
Carlos.

On 03/18/2015 09:29 AM, Siddhesh Poyarekar wrote:
> +@comment envz.h +@comment GNU +@deftypefun {void} envz_remove
> (char **@var{envz}, size_t *@var{envz_len}, const char
> *@var{name}) +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} +The
> @code{envz_remove} function removes an entry named @var{name} from 
> +@var{envz}, updating @code{*@var{envz}} and
> @code{*@var{envz_len}}. +@end deftypefun

The safety annotations are incorrect, see envz_add and argz_delete:

@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
@c Calls envz_remove, which calls enz_entry and argz_delete, and then
@c argz_add or equivalent code that reallocs and appends name=value.

@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
@c Calls free if no argument is left.