Hi Alejandro, Alejandro Colomar wrote on Sat, Aug 27, 2022 at 02:15:32PM +0200: > On 8/27/22 13:10, Ingo Schwarze wrote: >> Alejandro Colomar wrote: >>> -.BI "char *getcwd(char *" buf ", size_t " size ); >>> +.BI "char *getcwd(char " buf [ size "], size_t " size ); >> I dislike this. >> >> Manual pages should show function prototypes as they really are in >> the header file, or if the header file contains useless fluff like >> "restrict", a shortened form showing the essence that actually matters >> for using the API. > Regarding restrict, it is essential to differentiate memcpy(3) and > memmove(3), which are otherwise identical: > > void *memmove(void *dest, const void *src, size_t n); > > void *memcpy(void *restrict dest, const void *restrict src, > size_t n); Actually, the syntax of both is identical, only the semantics differ. That said, you are right that using memcpy(3) when memmove(3) is required is a famous and widespread bug. I doubt putting "restrict" into the SYNOPSIS will discourage careless programmers from making that mistake though. To me, "restrict" feels like a specialized tool for people writing compiler optimizers, not like something important enough to clutter API documenation. > Do you regard the (abused) VLA syntax as something much worse than the > use of restrict? Or are they more or less equivalent to you? If your implementation really contains "restrict" in the header file and it's standardized, putting it into the SYNOPSIS seems acceptable to me. Not necessary though and maybe somewhat noisy and distracting. Putting something that is not in the implementation and/or not in the standard into the SYNOPSIS seems much worse to me. And invalid syntax in the SYNOPSIS is even worse than that. For example, people may attempt to use SYNOPSIS as an example when designing their own, private function for a similar but not identical purpose and end up writing non-portable code, or even code that does not compile anywhere. They may be wrong if they blame you for that, but i doubt they will thank you. >> They should certainly not show something imaginary >> that does not match reality, and even less so using invalid syntax. > Well, not that I haven't had those thoughts, but we already use ilegal > syntax in some cases for good reasons. See for example open(2): > > int open(const char *pathname, int flags); > int open(const char *pathname, int flags, mode_t mode); > > Of course, you can't declare two conflicting prototypes like that. This does not seem quite as horrifying as char *getcwd(char buf[size], size_t size); because at least each of the prototypes is valid. My main concern about it would be that it is likely to make some people think (and C++ programmers in particular :-/) that there is type checking for the third and subsequent arguments, in which case they will be unpleasantly surprised when accidentally writing something like open(pathname, flags, &some_var, mode); and finding out later that it compiled and ran just fine, but the resulting file wasn't quite as confidential as they hoped. Explicitly displaying the ... to indicate the variable number of arguments, by contrast, makes it very clear that an API is almost certainly unusually dangerous and needs to be used with especial diligence. Either way, certainly not quite as bad as invalid syntax inside a prototype... Yours, Ingo
