Message-Id: <5.0.1.4.0.20001125025008.00a4bc20@pop5.banet.net> X-Sender: usbanet DOT farley3 AT pop5 DOT banet DOT net X-Mailer: QUALCOMM Windows Eudora Version 5.0.1 Date: Sat, 25 Nov 2000 03:33:05 -0500 To: Eli Zaretskii From: "Peter J. Farley III" Subject: Re: How are include/*.h headers maintained? Cc: djgpp-workers AT delorie DOT com In-Reply-To: <3405-Sat25Nov2000092616+0200-eliz@is.elta.co.il> References: <5 DOT 0 DOT 1 DOT 4 DOT 0 DOT 20001125013858 DOT 00a5dcc0 AT pop5 DOT banet DOT net> <5 DOT 0 DOT 1 DOT 4 DOT 0 DOT 20001125013858 DOT 00a5dcc0 AT pop5 DOT banet DOT net> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii"; format=flowed Reply-To: djgpp-workers AT delorie DOT com Errors-To: nobody AT delorie DOT com X-Mailing-List: djgpp-workers AT delorie DOT com X-Unsubscribes-To: listserv AT delorie DOT com Precedence: bulk At 09:26 AM 11/25/00 +0200, Eli Zaretskii wrote: >> Warning: I have changed several wrap settings in my mail program, so >> this message may or may not wrap well. > >Can't really judge that, since you forgot to attach the code ;-) I didn't actually intend to send any code with that message, but I did not know how the changes I made would affect the message itself, so I erred on the side of too much information. Looks good so far, I won't send extraneous warnings again. >Why do you need the string descriptions of DOS errors? Isn't it >enough to pass the DOS error code to __doserr_to_errno and then use >strerror or perror? Well, for one thing I did *not* know that __doserr_to_errno existed... It seems not to be documented anywhere in the info docs. I tried it in the test program, and it seems (IMHO) less useful for the detailed information one needs at this level. The DOS error meaning is not quite the same as the approximation returned by __doserr_to_errno. Here is a small example of all of the error strings for a failed locking call in my fcntl test program: DOS errno: 4 : Permission denied (EACCES) DOS error to errno: 32 : Operation not permitted (EPERM) Extended DOS error information: Extended error: 33 : lock violation Class: 0A : media error Action: 02 : prompt user to reenter input Error Locus: 02 : network related In this case, I would really like to see the "lock violation" message, to ensure I have programmed the locking code correctly. EPERM is a reasonable substitute, but (again IMHO) it doesn't give as much information as "lock violation" does. The int21/5C call returns one of four error values. Here are those values and the __doserr_to_errno substitutes: 01h (1) function number invalid EINVAL Invalid argument 06h (6) invalid handle EBADF Bad file descriptor 21h (33) lock violation EPERM Operation not permitted 24h (36) sharing buffer overflow ENOLCK No locks available In the __doserr_to_errno mapping, there are 16 different DOS errors that result in EPERM, 3 that result in EBADF, 2 that result in ENOLCK and 102 that result in EINVAL. In each circumstance, of course, we are probably only looking at a few possible errors being returned, and as long as each real DOS error has a unique mapping for the possible errors from each DOS call (which I have not verified), I suppose __doserr_to_errno would do just fine. But can it hurt to have more DOS-specific messages available if we want/need them? Like when we get an unexpected or undocumented return value that just maps to EINVAL, for instance? >> I developed a set of new DOS-only functions patterned >> after strerror() to produce the strings describing the four values >> returned by dosexterr(). To integrate it into the libc source tree >> properly, I believe I need to add these four functions to the >> include/dos.h header, where dosexterr() is defined. I would propose >> putting these new functions in the libc/dos/compat directory where >> dosexterr() resides. > >I think it's fine to add such functions in these places. Good, I'm glad I got that right. >>Is the correct way to change include/dos.h to directly modify it, or >>is there an automated process that maintains it from some other >>source? > >dos.h is an original file, not a derived file. You alter it directly >and then send the diffs, like you do with library source files. Understood. Thanks for verifying that. >> I also realize that I must write a *.txh file to document the new >> functions > >Yes. Also, please add a short paragraph to src/docs/kb/wc204.txi. >If you wish, you could add the descriptions of the new functions to >the existing .txh file in the directory where you add the functions. >Having one .txh file per function is not a mandatory requirement. Well, I'd like to add it to src/docs/kb/wc204.txi, but I only have src/docs/kb/wc20[123].txi from djlsr203.zip. Is there somewhere I need to go to get a v204 WIP zipfile? Is there such a collection? There is a .txh file for dosexterr already, and that seems to be a logical place to add it. There will be less duplication of text that way, since the errors are already listed in the existing file. >> but it looks to me like those are just for documentation, >> not for building *.h files. > >??? *.txh files are used to build libc.info, so you need to write up >the docs, but what does that have to do with building .h files? The >only connection is that if the .h file defines some symbols or macros >that users should know about, they, too, should be described in the >..txh file. My misunderstanding. I didn't know if they had anything to do with the .h files or not, but I have seen packages (perl is an example) where docs and code are in one file, which some make-time process separates into generated files. In these cases, you *must not* modify the generated files, because your changes will be lost the next time you issue a make. I was just checking to be sure I didn't have to be careful here in libc. Thanks for the prompt reply, Eli. Hopefully I'll be sending an updated version of the locking fcntl code in the next few days, along with these new error functions. Bye for now. --------------------------------------------------------- Peter J. Farley III (pjfarley AT dorsai DOT org OR pjfarley AT banet DOT net)