X-Authentication-Warning:	delorie.com: mail set sender to djgpp-bounces using -f
X-Received:	by 10.182.102.34 with SMTP id fl2mr4720855obb.16.1405738014541;
	Fri, 18 Jul 2014 19:46:54 -0700 (PDT)
X-Received:	by 10.50.39.16 with SMTP id l16mr219384igk.7.1405738014386; Fri,
	18 Jul 2014 19:46:54 -0700 (PDT)
Newsgroups:	comp.os.msdos.djgpp
Date:	Fri, 18 Jul 2014 19:46:53 -0700 (PDT)
In-Reply-To:	<op.xi6t2m0o6zenlw@localhost>
Complaints-To:	groups-abuse AT google DOT com
Injection-Info:	glegroupsg2000goo.googlegroups.com; posting-host=2601:7:f00:2ca:576:b0ea:98c9:2968;
	posting-account=05hOMwoAAAB6R8xtiQKzEljSMzgOhVF1
NNTP-Posting-Host:	2601:7:f00:2ca:576:b0ea:98c9:2968
References:	<e85a8d16-77d6-46d9-81fb-a1e3537172bb AT googlegroups DOT com> <op DOT xi6t2m0o6zenlw AT localhost>
User-Agent:	G2/1.0
MIME-Version:	1.0
Message-ID:	<a1e807a0-4681-4b35-8371-a62e9f680565@googlegroups.com>
Subject:	Re: scrambled documentation for _dosmemput*, please fix
From:	Jim Michaels <jmichae3 AT yahoo DOT com>
Injection-Date:	Sat, 19 Jul 2014 02:46:54 +0000
Bytes:	4797
Lines:	92
To:	djgpp AT delorie DOT com
DJ-Gateway:	from newsgroup comp.os.msdos.djgpp
X-MIME-Autoconverted:	from quoted-printable to 8bit by delorie.com id s6J302dt023724
Reply-To:	djgpp AT delorie DOT com
Errors-To:	nobody AT delorie DOT com
X-Mailing-List:	djgpp AT delorie DOT com
X-Unsubscribes-To:	listserv AT delorie DOT com

On Friday, July 18, 2014 3:00:12 AM UTC-7, Rod Pemberton wrote:
> On Thu, 17 Jul 2014 21:53:59 -0400, Jim Michaels
> 
> wrote:
> 
> 
> 
> > the example doesn't match the declaration for _dosmemput*.
> 
> > please fix. I am trying to implement some code with these
> 
> > functions, and the documentation has the arguments scrambled.
> 
> 
> 
> I haven't been keeping track of mistakes in
> libc.info.  I know that there are a bunch of
> spelling errors.  They're easily found by any
> modern word processor.  Well, that's not good.
> It seems libc.info for DJGPP v2.03 from libc.tex,
> is rife with spelling errors:

I should be more specific. the arguments in the example and the arguments in the func declaration are swapped. I think the example is in error, looking at the .h file. spelling errors I can live with as long as the function names are spelled correctly.

Thu 07/17/2014 18:54:50.37|D:\djc472\include\sys|>grep dosmemput *
farptr.h
movedata() or dosmemget/dosmemput().
dosmemget, dosmemput) use %gs.  Still, you should be careful about
movedata.h
void dosmemput(const void *_buffer, size_t _length, unsigned long _offset);
void _dosmemputb(const void *_buffer, size_t _xfers, unsigned long _offset);
void _dosmemputw(const void *_buffer, size_t _xfers, unsigned long _offset);
void _dosmemputl(const void *_buffer, size_t _xfers, unsigned long _offset);

the example shows:
	
unsigned short save_screen[25][80];
_dosmemputb(save_screen, 0xb8000, 80*2*25);

the count and offset are swapped. sorry for not making a formal bug report.
the example should be:

unsigned short save_screen[25][80];
_dosmemputb(save_screen, 80*2*25, 0xb8000);

the problem is in:
http://www.delorie.com/djgpp/doc/libc/libc_194.html
http://www.delorie.com/djgpp/doc/libc/libc_195.html
http://www.delorie.com/djgpp/doc/libc/libc_196.html
http://www.delorie.com/djgpp/doc/libc/libc_197.html

the URL info should help you locate the file to edit easier (I know this helps me with my web sites). I usually try not to be ambiguous, but I slipped up this time.

while you are at it, please change this mostly similar text across the 4 pages wording to something a bit more accurate and descriptive about the conventional memory "offset" argument:

" Description

This function transfers data from the program's virtual address space to MS-DOS's conventional memory space, using only byte (8-bit) transfers. The offset is a physical address, which can be computed from a real-mode segment/offset pair as follows: "

to below (change denoted in square brackets):

" Description

This function transfers data from the program's virtual address space to MS-DOS's conventional memory space, using only byte (8-bit) transfers. The offset is a [DOS 640K conventional memory] physical address, which can be computed from a real-mode segment/offset pair as follows: "

this should clear up some ambiguities in the spec as to what's what. when I was going back to look at the memput api, I had a hard time from the description and func arg names figuring out what was the source and what was the target, what was DOS conventional memory, etc.

then I began to realize later on that copying argument-wise flows from left to right (sometimes API designers to right to left, like with strcpy). A little wording change should make things clearer.

this is an accurate change, is it not?

thanks folks.

- Raw text -