On Thu, Dec 07, 2023 at 09:50:35PM +0000, Lee Griffiths wrote: > (repost to mailing list, as my previous message attempt looked like > plain-text but was actually html) > > > > > Hi Lee! > > > Thanks for the report. After seeing how much frustration it has caused, > > I propose this change. Does it look good to you? > > I don't wish to bike-shed this (as the current man-page is fine by me) > and I have no idea on the style guide used by the man-pages, but if I > was making the change I would replace the 'deprecated' on every > integer specifier with "CAVEAT: SEE BUGS". That way the inexperienced > reader is still frightened into using the function carefully. But if > that kind of thing isn't allowed then the proposed patch looks good to > me. We could do that kind of thing. There are pages where the first line in the DESCRIPTION is something like 'Never use this function.' (that exact text appears in gets(3)). > > As a general point: A _lot_ of inexperienced users use this function > to parse user input. At the start of every semester you see an influx > of "why is my use of scanf broken?" posts on the various C and > learn-programming based subreddits, as well as Stackoverflow. Not exactly. This page is only about sscanf(3), which is not as bad as scanf(3). For scanf(3), I've re-read the page after these discussions, and have added some more text, documenting some of the problems: - <https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=4ea602c6ab2716c00d189d28199a9236180d2145> - <https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=8c3bd620bca7de41c9d3e28d73f09ec88fd52a86> > I have > no idea why but it seems there's a large body of professors out there > teaching people to use scanf() instead of getc() or fgets() etc, so > I'm of the opinion that the scanf() page needs to be as scary as > possible :) My guess is that the old manual page wasn't scary enough (if at all). I've done a few steps to try to prevent that. Split [f]scanf(3) from sscanf(3). The latter is not so bad, since it doesn't need to differentiate newlines from other white space, and it doesn't leave the unrecognized text in the input stream. So, the new page for sscanf(3) is what documents the conversions and all that, and the new page for scanf(3) (and fscanf(3)) is shorter and just recommending avoiding these functions at all (but still referring to sscanf(3) for documentation of the conversions). > > Again, I know nothing about how man pages are written, but if it was > documentation for legacy code I'd inherited I'm make sure to stress > the following somewhere on the page: We have man-pages(7) with a small style guide. > 1. scanf() is intended to parse FORMATTED input, i.e. it consumes the > kind of strings produced by printf(), and NOT user input. (I'm not > 100% sure if K&R had that as their rationale, but that's the way it's > designed now. Though this might confuse people into thinking they can > use their similar, but not identical, format strings between printf > and scanf!). Currently the word "format" or "formatted" barely > appears. But it's this feature that distinguishes it from the other > parsing functions. Agree. I've added this commit: <https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=bb4dbdb82f141f6394984aced67d65810ec7f747> > 2. Things like fgets() are much better for consuming user input, which > you can then parse with all the other functions. That's already specified in scanf(3), in the first paragraph: DESCRIPTION The scanf() family of functions scans input like sscanf(3), but read from a FILE. It is very difficult to use these functions correctly, and it is preferable to read entire lines with fgets(3) or getline(3) and parse them later with sscanf(3) or more specialized functions such as strtol(3). Thanks, Alex -- <https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
