Bug 75995

Summary: hcreate(3) documentation(?) bug
Product: Documentation Reporter: Tarc <tarc>
Component: Books & ArticlesAssignee: Daniel Gerzo <danger>
Status: Closed FIXED    
Severity: Affects Only Me    
Priority: Normal    
Version: Latest   
Hardware: Any   
OS: Any   

Description Tarc 2005-01-09 16:20:21 UTC
I read the man hcreate(3) and, for better understanding, how hash table addressed, /usr/src/lib/libc/stdlib/hcreate.c
Mam says, that if error occur, hcreate(3) returns 0, but if no memory, it will set errno to ENOMEM.
But I see, that if hachtable is already created, hcreate returns 0 AND SETS errno to EINVAL.
T think, it's true way, but undocumented

Fix: 

Add description about EINVAL to man, or don't set errno.
How-To-Repeat: up to date system sources & read:
cd /usr/src/lib/libc/stdlib
more hcreate.c
man 3 hcreate
Comment 1 minimarmot 2008-07-02 05:03:45 UTC
It definitely looks like a documentation bug.

I've put a patch up at
http://stuff.mit.edu/afs/sipb.mit.edu/user/kaduk/freebsd/patches/htcreate.diff.2008.07.01
in case gmail mangles the whitespace.

Thanks to sbahra on #bsddocs for pointing out that we should mention that
errno gets set.

-Ben Kaduk

--- hcreate.3.0 2008-07-01 23:29:00.000000000 -0400
+++ hcreate.3   2008-07-01 23:53:17.000000000 -0400
@@ -1,6 +1,6 @@
 .\" $FreeBSD: src/lib/libc/stdlib/hcreate.3,v 1.5 2005/01/20 09:17:04 ru Exp $
 .\"
-.Dd May 8, 2001
+.Dd July 1, 2008
 .Os
 .Dt HCREATE 3
 .Sh NAME
@@ -23,6 +23,7 @@
 and
 .Fn hsearch
 functions manage hash search tables.
+Only one hash table per process may be active at any given time.
 .Pp
 The
 .Fn hcreate
@@ -111,7 +112,7 @@
 .Sh RETURN VALUES
 The
 .Fn hcreate
-function returns 0 if it cannot allocate sufficient space for the table;
+function returns 0 if the table creation failed;
 otherwise, it returns non-zero.
 .Pp
 The
@@ -199,6 +200,8 @@
 .Bl -tag -width Er
 .It Bq Er ENOMEM
 Insufficient storage space is available.
+.It Bq Er EINVAL
+A table already exists.
 .El
 .Sh SEE ALSO
 .Xr bsearch 3 ,
Comment 2 Daniel Gerzo freebsd_committer freebsd_triage 2008-07-06 13:18:15 UTC
Responsible Changed
From-To: freebsd-doc->danger

Take
Comment 3 dfilter service freebsd_committer freebsd_triage 2008-07-06 13:18:20 UTC
danger      2008-07-06 12:17:53 UTC

  FreeBSD src repository

  Modified files:
    lib/libc/stdlib      hcreate.3 
  Log:
  SVN rev 180325 on 2008-07-06 12:17:53Z by danger
  
  - Add description about a missing return value
  
  PR:             docs/75995
  Submitted by:   Tarc <tarc@po.cs.msu.su>
  MFC after:      3 days
  
  Revision  Changes    Path
  1.6       +6 -2      src/lib/libc/stdlib/hcreate.3
_______________________________________________
cvs-all@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/cvs-all
To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
Comment 4 Daniel Gerzo freebsd_committer freebsd_triage 2008-07-06 13:18:28 UTC
State Changed
From-To: open->patched

- Fixed in HEAD, awaiting for MFC
Comment 5 dfilter service freebsd_committer freebsd_triage 2008-07-11 10:35:42 UTC
danger      2008-07-11 09:35:20 UTC

  FreeBSD src repository

  Modified files:        (Branch: RELENG_7)
    lib/libc/stdlib      hcreate.3 
  Log:
  SVN rev 180441 on 2008-07-11 09:35:20Z by danger
  
  MFC r180325 and r180329:
  
  - This code was intially obtained from NetBSD, but it's missing licence
    statement. Add the one from the current NetBSD version.
  - Add description about a missing return value [1]
  
  PR:             docs/75995
  Submitted by:   Tarc <tarc@po.cs.msu.su>
  
  Revision  Changes    Path
  1.5.10.1  +35 -3     src/lib/libc/stdlib/hcreate.3
_______________________________________________
cvs-all@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/cvs-all
To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
Comment 6 Daniel Gerzo freebsd_committer freebsd_triage 2008-07-11 10:37:37 UTC
State Changed
From-To: patched->closed

I have merged my changes back to RELENG_[76]. Close this one.
Comment 7 dfilter service freebsd_committer freebsd_triage 2008-07-11 10:37:44 UTC
danger      2008-07-11 09:37:24 UTC

  FreeBSD src repository

  Modified files:        (Branch: RELENG_6)
    lib/libc/stdlib      hcreate.3 
  Log:
  SVN rev 180442 on 2008-07-11 09:37:24Z by danger
  
  MFC r180325 and r180329:
  
  - This code was intially obtained from NetBSD, but it's missing licence
    statement. Add the one from the current NetBSD version.
    - Add description about a missing return value [1]
  
  PR:             docs/75995
  Submitted by:   Tarc <tarc@po.cs.msu.su>
  
  Revision  Changes    Path
  1.5.2.1   +35 -3     src/lib/libc/stdlib/hcreate.3
_______________________________________________
cvs-all@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/cvs-all
To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"