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: 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: User-Agent: G2/1.0 MIME-Version: 1.0 Message-ID: Subject: Re: scrambled documentation for _dosmemput*, please fix From: Jim Michaels Injection-Date: Sat, 19 Jul 2014 02:46:54 +0000 Content-Type: text/plain; charset=ISO-8859-1 Bytes: 4797 Lines: 92 To: djgpp AT delorie DOT com DJ-Gateway: from newsgroup comp.os.msdos.djgpp Content-Transfer-Encoding: 8bit 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 Precedence: bulk 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.