From owner-freebsd-current@FreeBSD.ORG  Tue Nov 29 11:07:38 2005
Return-Path: <owner-freebsd-current@FreeBSD.ORG>
X-Original-To: current@freebsd.org
Delivered-To: freebsd-current@FreeBSD.ORG
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id A7F0216A41F;
	Tue, 29 Nov 2005 11:07:38 +0000 (GMT)
	(envelope-from sobomax@portaone.com)
Received: from www.portaone.com (web.portaone.com [195.70.151.35])
	by mx1.FreeBSD.org (Postfix) with ESMTP id D1D5043D53;
	Tue, 29 Nov 2005 11:07:37 +0000 (GMT)
	(envelope-from sobomax@portaone.com)
Received: from [192.168.1.2] (S0106000f3d63befd.vs.shawcable.net
	[70.71.19.119]) (authenticated bits=0)
	by www.portaone.com (8.12.11/8.12.11) with ESMTP id jATB7VEw083667
	(version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO);
	Tue, 29 Nov 2005 12:07:33 +0100 (CET)
	(envelope-from sobomax@portaone.com)
Message-ID: <438C3672.1010700@portaone.com>
Date: Tue, 29 Nov 2005 03:07:30 -0800
From: Maxim Sobolev <sobomax@portaone.com>
Organization: Porta Software Ltd
User-Agent: Thunderbird 1.5 (Windows/20051025)
MIME-Version: 1.0
To: phk@freebsd.org
Content-Type: text/plain; charset=KOI8-U; format=flowed
Content-Transfer-Encoding: 7bit
X-Virus-Scanned: ClamAV 0.86.2/1198/Tue Nov 29 11:05:20 2005 on
	www.portaone.com
X-Virus-Status: Clean
X-Spam-Status: No, score=-0.6 required=5.0 tests=BAYES_00,RCVD_IN_SORBS_DUL 
	autolearn=no version=3.0.0
X-Spam-Checker-Version: SpamAssassin 3.0.0 (2004-09-13) on www.portaone.com
Cc: "current@freebsd.org" <current@freebsd.org>
Subject: Correct usage of g_read_data() API
X-BeenThere: freebsd-current@freebsd.org
X-Mailman-Version: 2.1.5
Precedence: list
Reply-To: Maxim.Sobolev@portaone.com
List-Id: Discussions about the use of FreeBSD-current
	<freebsd-current.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-current>, 
	<mailto:freebsd-current-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/freebsd-current>
List-Post: <mailto:freebsd-current@freebsd.org>
List-Help: <mailto:freebsd-current-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/freebsd-current>,
	<mailto:freebsd-current-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Tue, 29 Nov 2005 11:07:38 -0000

Hi Poul,

After making a fix for geom_label (rev.1.4 of g_label_ntfs.c) I have 
decided to check if there are any other places which don't check return 
values of g_read_data(9).

What I found however is that there are several different usage patterns, 
some of which rely on undocumented internal properties of the said API, 
particularly:

--- 1 ---
error = random();
data = g_read_data(..., &error);
if (error != 0)
	handle_error(error);
---------

--- 2 ---
error = random();
data = g_read_data(..., &error);
if (buf == NULL || error != 0)
	handle_error(error);
---------

--- 3 ---
error = random();
data = g_read_data(..., &error);
if (buf == NULL)
	handle_error(error);
---------

According to my reading of g_read_data(9) only (3) is valid, since both 
(1) and (2) assume that error will always be cleared on successful 
completion, while (1) also assumes that error will be set to non-zero 
value in all cases when error happens and (2) assumes that non-NULL 
value can be returned even on error.

Therefore, either documentation should be extended to match 
implementation or usage of g_read_data() fixed in all places where it is 
incorrect.

Please advise.

-Maxim
P.S. I can do the actual changes by myself, both to documentation and/or 
to code.