Date: Thu, 04 Jul 2002 13:59:07 +0100 From: "Richard Dawe" Sender: rich AT phekda DOT freeserve DOT co DOT uk To: djgpp-workers AT delorie DOT com X-Mailer: Emacs 21.3.50 (via feedmail 8.3.emacs20_6 I) and Blat ver 1.8.6 Subject: Patch: Various symlink-related documentation updates Message-Id: Reply-To: djgpp-workers AT delorie DOT com Hello. Below is a patch to address the following: * lstat's info page doesn't say when you should use it. * stat's info page doesn't say when you should use it. * FSEXT info pages don't say whether the paths passed to the handlers have symlinks resolved or not. I added sections to the lstat and stat pages explaining their differences and when you should use the other. I added some info to the FSEXT page about the paths. There's a patch below. OK to commit? Thanks, bye, Rich =] Index: src/libc/posix/sys/stat/lstat.txh =================================================================== RCS file: /cvs/djgpp/djgpp/src/libc/posix/sys/stat/lstat.txh,v retrieving revision 1.4 diff -p -u -3 -r1.4 lstat.txh --- src/libc/posix/sys/stat/lstat.txh 1 Dec 2001 20:22:37 -0000 1.4 +++ src/libc/posix/sys/stat/lstat.txh 4 Jul 2002 12:49:20 -0000 @@ -10,7 +10,11 @@ int lstat(const char *file, struct stat @subheading Description This function obtains the status of the file @var{file} and stores -it in @var{sbuf}, which has this structure: +it in @var{sbuf}. If @var{file} is a symbolic link, then @code{lstat} +returns information about the symbolic link. To get information about +the target of a symbolic link, use @code{stat} (@pxref{stat}) instead. + +@var{sbuf} has this structure: @smallexample struct stat @{ Index: src/libc/posix/sys/stat/stat.txh =================================================================== RCS file: /cvs/djgpp/djgpp/src/libc/posix/sys/stat/stat.txh,v retrieving revision 1.9 diff -p -u -3 -r1.9 stat.txh --- src/libc/posix/sys/stat/stat.txh 1 Dec 2001 20:22:37 -0000 1.9 +++ src/libc/posix/sys/stat/stat.txh 4 Jul 2002 12:49:20 -0000 @@ -10,7 +10,11 @@ int stat(const char *file, struct stat * @subheading Description This function obtains the status of the file @var{file} and stores -it in @var{sbuf}, which has this structure: +it in @var{sbuf}. @code{stat} follows symbolic links. To get +information about a symbolic link, use @code{lstat} (@pxref{lstat}) +instead. + +@var{sbuf} has this structure: @smallexample struct stat @{ Index: src/libc/fsext/fsext.txh =================================================================== RCS file: /cvs/djgpp/djgpp/src/libc/fsext/fsext.txh,v retrieving revision 1.14 diff -p -u -3 -r1.14 fsext.txh --- src/libc/fsext/fsext.txh 11 Jun 2002 08:16:55 -0000 1.14 +++ src/libc/fsext/fsext.txh 4 Jul 2002 12:49:23 -0000 @@ -29,6 +29,13 @@ A no-op. This is currently unused by th An open handler (@pxref{_open}). This is called just before the library is about to issue the DOS OpenFile call on behalf of your program. + +If @code{_open} was called from the library function @code{open}, +then the path passed to the handler will have either +all its symlink components resolved or will refer to a symlink file +(i.e.: all directory symlinks will be resolved), depending +on whether the @code{O_NOLINK} was passed to @code{open} (@pxref{open}). + Do not use this extension to emulate symlinks. Use @code{__FSEXT_readlink} handler instead. @@ -38,6 +45,10 @@ A create handler (@pxref{_creat}, and @p a file needs to be created. Note that the handler should both create the ``file'' and open it. +If @code{_creat} or @code{_creatnew} were called from +the library functions @code{open} or @code{creat}, then the path passed +to the handler will have all its symlink components resolved. + @item __FSEXT_read A read handler (@pxref{_read}). Called when data should be read from @@ -98,11 +109,16 @@ A file llseek handler (@pxref{llseek}). A file link handler (@pxref{link}). This is most relevant to file system extensions that emulate a directory structure. +The source and destination paths are passed to the handler unchanged. + @item __FSEXT_unlink A file unlink handler (@pxref{remove}, and @pxref{unlink}). This is most relevant to file system extensions that emulate a directory structure. +The path passed to the handler will have all its directory symlinks +resolved, so it may refer to a symlink file. + @item __FSEXT_dup A file dup handler (@pxref{dup}). This is called when a new @@ -119,6 +135,13 @@ A file lstat handler (@pxref{lstat}). T information about stated file. If you provide this hook, function @code{stat} will be hooked too, as @code{stat} always calls @code{lstat}. +If the handler is called as a result of a @code{stat} call, then +the path passed to the handler will have all its symlinks resolved, +so it will refer to a ``regular'' file. If the handler is called +as result of a @code{lstat} call and not a @code{stat} call, +then the path passed to the handler will have all its directory symlinks +resolved, so it may refer to a symlink file. + @item __FSEXT_fstat A file fstat handler (@pxref{fstat}). The extension should fill in @@ -129,10 +152,15 @@ various status information about the emu A file readlink handler (@pxref{readlink}). This extension should be used to provide support for symlinks in some other than DJGPP format. +The path passed to the handler will have all its directory symlinks +resolved, so it may refer to a symlink file. + @item __FSEXT_symlink A file symlink handler (@pxref{symlink}). This extension should create symlinks in other than DJGPP symlink file format. + +The source and destination paths are passed to the handler unchanged. @item __FSEXT_fchown