_____________________________________________________________________________
Notice: This is an unapproved draft interpretation. Use at
your own risk.  


 _____________________________________________________________________________
 					Austin Group Interpretation reference
							1003.1-2001  #081

 _____________________________________________________________________________

	Interpretation Number:	081
	Topic:			 getgrnam_r return value
	Relevant Sections:	 XSH getgrnam_r



Austin Group Interpretation Request:
------------------------------------

        Date:  Fri, 2 Dec 2005 16:50:01 GMT


------------------------------------------------------------------------ 

 7  Defect Report concerning (number and title of International Standard
    or DIS final text, if applicable): 

The XSH  Volume of IEEE Std 1003.1-2001

------------------------------------------------------------------------ 

 8  Qualifier (e.g. error, omission, clarification required):

 3. Clarification required

------------------------------------------------------------------------ 

 9  References in document (e.g. page, clause, figure, and/or table
    numbers):

 Page: 520  Line: 17147-17148  Section: getgrnam,

bug2.txt  Enhancement Request Number 118

------------------------------------------------------------------------ 

10  Nature of defect (complete, concise explanation of the perceived
    problem):

 Problem:

 For both getgrnam and getgrnam_r the specification is a bit unclear in
 terms what is returned, when no entry has been found.


 getgrnam()

 SUSv3: "The getgrnam() function shall return a null pointer if either
 the requested entry was not found, or an error occurred. On error,
 errno shall be set to indicate the error."


 Ok, I'd expect that getgrnam("noExist") == NULL, but it is not clearly
 stated whether the errno may be changed or not.  I read this as: errno
 stays that value and is not touched.

 Others regard this a undefined by the spec. (GNU Libc maintainer: "The
 code always did signal a missing entry with a NULL pointer and
 ENOENT.  There is nothing in POSIX which prohibits this.  The POSIX
 spec just said what has to happen for the error condit


 getgrnam_r()

 Description: "A NULL pointer is returned at the location pointed to by
 result on error or if the requested entry is not found."

 Returned value: "If successful, the getgrnam_r() function shall return
 zero; otherwise, an error number shall be returned to indicate the
 error."

 It is a bit unclear whether the error number is zero or not if entry
 has been found.


------------------------------------------------------------------------ 

11  Solution proposed by the submitter (optional):

 Action:

 a) Clearify whether errno (getgrnam) is modified when no entry has
 been found

 b) Clearify whether not found is "successful", i.e. whether zero is
 returned or not.


------------------------------------------------------------------------ 

Interpretation response
------------------------
The standard is unclear on this issue and concerns have been raised
about this which are being referred to the sponsor.

Rationale:
----------
The working group developers felt that the intent is that
if no error occurs but an entry is not found, getgrnam() returns a
null pointer  and getgrnam_r() returns zero and set the pointer
pointed to by result to a null pointer and neither getgrnam()
nor getgrnam_r() should change errno in this case.  If an
error occurs, the return value is the same as stated 
except that the error indicate will also be set to
indicate which error was detected.

Notes to the Editor for a future revision (not part of this interpretation):
---------------------------------------------------------------------------

On getgrnam(), page 519 line 17133
Change the RETURN VALUE from:
"If successful, the getgrnam_r( ) function shall return zero; otherwise,
an error number shall be  returned to indicate the error."

To:
"The getgrnam_r() function shall return zero on success
or if the requested entry was not found and no error has occurred.
If an error has occured an error number shall be returned to indicate
the error."



Forwarded to Interpretations Group: Tue Mar 14 11:04:54 GMT 2006
Proposed resolution: Tue Mar 14 11:04:54 GMT 2006
Approved: Thu Apr 20 10:30:20 BST 2006