Documentation for utime should be improved

[p5pRT]

Migrated from rt.perl.org#3274 (status was 'resolved')

Searchable as RT3274$

[p5pRT]

From Steve.Tolkin@fmr.com

Created by steve.tolkin@fmr.com

The documentation for utime should be improved\, as follows​:

Please change the man page for the utime() function. It should add something like​: Certain file systems can only store the time with a granularity (precision) of 2 seconds. Some systems known to have this limitation are the FAT file system used in DOS and various Microsoft Windows file systems derived from it. This is a limitation of the file system\, not of utime.

Change perlfaq5 to have similar language\, instead of the current wording "doesn't work correctly with Win95/NT" which is both vague and imappropriately scary.

There was some discussion of this in news//comp.lang.perl.moderated under the subject Does utime work correctly on Windows NT perl? and date beginning 2000-05-19

In addition please add the words "utime" and "touch" to the *question* "How do I set a file's timestamp?" in perlfaq5.

The point is to allow the command "perldoc -q touch" to find this question and answer.
Perldoc -q only searches the text of the *question*.

In general adding one or two words to the the question that gives the answer is a usefull approach to other FAQ questions too. I spent a while searching for "touch" before I found utime by looking at the names of all the perl functions.

Ideally touch would also be added to the perlfunc man page\, as a dummy entry\, just to refer to utime. A precedent for this has been established by including the non-existent function export.

Steven Tolkin steve.tolkin@​fmr.com 2000-05-22

Perl Info

``` Site configuration information for perl 5.00503: Configured by informix at Thu May 6 15:58:47 EDT 1999. Summary of my perl5 (5.0 patchlevel 5 subversion 3) configuration: Platform: osname=solaris, osvers=2.5.1, archname=sun4-solaris uname='sunos denmark 5.5.1 generic_103640-18 sun4u sparc sunw,ultra-2 ' hint=recommended, useposix=true, d_sigaction=define usethreads=undef useperlio=undef d_sfio=undef Compiler: cc='cc', optimize='-O', gccversion= cppflags='-I/usr/local/include' ccflags ='-I/usr/local/include' stdchar='unsigned char', d_stdstdio=define, usevfork=false intsize=4, longsize=4, ptrsize=4, doublesize=8 d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=16 alignbytes=8, usemymalloc=y, prototype=define Linker and Libraries: ld='cc', ldflags =' -L/usr/local/lib' libpth=/usr/local/lib /lib /usr/lib /usr/ccs/lib libs=-lsocket -lnsl -ldl -lm -lc -lcrypt libc=/lib/libc.so, so=so, useshrplib=false, libperl=libperl.a Dynamic Linking: dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags=' ' cccdlflags='-KPIC', lddlflags='-G -L/usr/local/lib' Locally applied patches: @INC for perl 5.00503: /local/home/fnx/steve/lib /local/home/fnx/lib/sun4-solaris /local/home/fnx/lib /usr/local/lib/perl5/5.00503/sun4-solaris /usr/local/lib/perl5/5.00503 /usr/local/lib/perl5/site_perl/5.005/sun4-solaris /usr/local/lib/perl5/site_perl/5.005 . Environment for perl 5.00503: HOME=/local/home/fnx LANG (unset) LANGUAGE (unset) LD_LIBRARY_PATH=/apps/informix/informix/lib:/apps/informix/informix/lib/esql LOGDIR (unset) PATH=/local/home/fnx/steve/scripts/misc:/local/home/fnx/steve/scripts:/local /home/sy71046/mybin:/local/home/fnx/scripts:/local/home/fnx/scripts/misc:/lo cal/home/fnx/bin:/usr/openwin/bin:/usr/bin:/local/home/fnx/jdk1.1.7A/bin:/ap ps/curamesg/2.1:.:/opt/UWpine/bin:/usr/local/bin:/usr/ucb:/usr/ccs/bin:/apps /informix/informix/bin:/usr/sbin PERL5LIB=/local/home/fnx/steve/lib:/local/home/fnx/lib PERL_BADLANG (unset) SHELL=/bin/ksh ```

[p5pRT]

From [Unknown Contact. See original ticket]

Created by steve.tolkin@fmr.com

The documentation for utime should be improved\, as follows​:

Please change the man page for the utime() function. It should add something like​: Certain file systems can only store the time with a granularity (precision) of 2 seconds. Some systems known to have this limitation are the FAT file system used in DOS and various Microsoft Windows file systems derived from it. This is a limitation of the file system\, not of utime.

Change perlfaq5 to have similar language\, instead of the current wording "doesn't work correctly with Win95/NT" which is both vague and imappropriately scary.

There was some discussion of this in news//comp.lang.perl.moderated under the subject Does utime work correctly on Windows NT perl? and date beginning 2000-05-19

In addition please add the words "utime" and "touch" to the *question* "How do I set a file's timestamp?" in perlfaq5.

The point is to allow the command "perldoc -q touch" to find this question and answer.
Perldoc -q only searches the text of the *question*.

In general adding one or two words to the the question that gives the answer is a usefull approach to other FAQ questions too. I spent a while searching for "touch" before I found utime by looking at the names of all the perl functions.

Ideally touch would also be added to the perlfunc man page\, as a dummy entry\, just to refer to utime. A precedent for this has been established by including the non-existent function export.

Steven Tolkin steve.tolkin@​fmr.com 2000-05-22

Perl Info

``` Site configuration information for perl 5.00503: Configured by informix at Thu May 6 15:58:47 EDT 1999. Summary of my perl5 (5.0 patchlevel 5 subversion 3) configuration: Platform: osname=solaris, osvers=2.5.1, archname=sun4-solaris uname='sunos denmark 5.5.1 generic_103640-18 sun4u sparc sunw,ultra-2 ' hint=recommended, useposix=true, d_sigaction=define usethreads=undef useperlio=undef d_sfio=undef Compiler: cc='cc', optimize='-O', gccversion= cppflags='-I/usr/local/include' ccflags ='-I/usr/local/include' stdchar='unsigned char', d_stdstdio=define, usevfork=false intsize=4, longsize=4, ptrsize=4, doublesize=8 d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=16 alignbytes=8, usemymalloc=y, prototype=define Linker and Libraries: ld='cc', ldflags =' -L/usr/local/lib' libpth=/usr/local/lib /lib /usr/lib /usr/ccs/lib libs=-lsocket -lnsl -ldl -lm -lc -lcrypt libc=/lib/libc.so, so=so, useshrplib=false, libperl=libperl.a Dynamic Linking: dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags=' ' cccdlflags='-KPIC', lddlflags='-G -L/usr/local/lib' Locally applied patches: @INC for perl 5.00503: /local/home/fnx/steve/lib /local/home/fnx/lib/sun4-solaris /local/home/fnx/lib /usr/local/lib/perl5/5.00503/sun4-solaris /usr/local/lib/perl5/5.00503 /usr/local/lib/perl5/site_perl/5.005/sun4-solaris /usr/local/lib/perl5/site_perl/5.005 . Environment for perl 5.00503: HOME=/local/home/fnx LANG (unset) LANGUAGE (unset) LD_LIBRARY_PATH=/apps/informix/informix/lib:/apps/informix/informix/lib/esql LOGDIR (unset) PATH=/local/home/fnx/steve/scripts/misc:/local/home/fnx/steve/scripts:/local /home/sy71046/mybin:/local/home/fnx/scripts:/local/home/fnx/scripts/misc:/lo cal/home/fnx/bin:/usr/openwin/bin:/usr/bin:/local/home/fnx/jdk1.1.7A/bin:/ap ps/curamesg/2.1:.:/opt/UWpine/bin:/usr/local/bin:/usr/ucb:/usr/ccs/bin:/apps /informix/informix/bin:/usr/sbin PERL5LIB=/local/home/fnx/steve/lib:/local/home/fnx/lib PERL_BADLANG (unset) SHELL=/bin/ksh ```

[p5pRT]

From @ysth

This is a bug report for perl from steve.tolkin@​fmr.com\, generated with the help of perlbug 1.26 running under perl 5.00503.

Ideally touch would also be added to the perlfunc man page\, as a dummy entry\, just to refer to utime. A precedent for this has been established by including the non-existent function export.

Where? I don't see any such thing.

[p5pRT]

From @tamias

On Wed\, Jun 07\, 2000 at 07​:25​:26PM -0700\, Yitzchak Scott-Thoennes wrote​:

This is a bug report for perl from steve.tolkin@​fmr.com\, generated with the help of perlbug 1.26 running under perl 5.00503.

Ideally touch would also be added to the perlfunc man page\, as a dummy entry\, just to refer to utime. A precedent for this has been established by including the non-existent function export.

Where? I don't see any such thing.

Steve may have meant import rather than export.

=item import

There is no builtin C\ function. It is just an ordinary method (subroutine) defined (or inherited) by modules that wish to export names to another module. The C\ function calls the C\ method for the package used. See also L\</use()>\, L\\, and L\.

I don't think that touch and import are similar cases\, however. import is not a builtin\, but it is part of the core.

Ronald

[p5pRT]

From [Unknown Contact. See original ticket]

Dear Ronald\,   Yes\, I meant import. And yes\, I can see why import is different than touch.

My general objective in posting this (and a few others) to c.l.p.moderated is to help perl users find what they are looking for in *documentation* (including the man pages and the FAQ).

I went looking to a function that did the equivalent of Unix "touch". I could not find it by any kind of search. I finally found it by accident. That seems wrong\, and fixable. I probably would have eventually done something like perldoc perlfunc | cgrep.pl touch

The entry for utime does mention touch\, so if the man page was an plain old book\, with a human created index\, this would likely be in the index. I want to understand how to solve this specific problem\, and many others like it\, in a way that is compatible with "perldoc -f touch" finding it.

I want an entry such as "touch -- see utime". The question is\, where to put such an entry.

One part of the solution is to use the word touch\, and utime\, in the *question* in the FAQ about changing a file's modification time. Then perldoc -q touch would find it\, under the question​: "How do I set a file's timestamp in perl?"

We can always omit the string "in perl" from the questions\, to save space. So maybe the simplest solutiuon is to reword this to include a few more keywords in the question\, e.g. "How do I set a file's timestamp? (touch\, utime)"

A more comprehensive approach would be to add other questions that use the other words a user might search on\, and the refer to the original question\, e.g. How can I use touch to change the date or time a file was modified?   See the question​: How do I set a file's timestamp?

It would be useful to extend the capability of perldoc to support multiple arguments to -q (or a new option letter) meaning find all these strings in the question.

It would also be useful to add a new option meaning find all these strings in the answer. (Or similarly in the pod section for a function\, etc.)

I will post to perlbug\, as a doc "bug"\, once I have a concrete suggestion to make as to how to fix the doc.

Steve

-----Original Message----- From​: Ronald J Kimball [mailto​:rjk@​linguist.dartmouth.edu] Sent​: Wednesday\, June 07\, 2000 10​:37 PM To​: Yitzchak Scott-Thoennes Cc​: perl5-porters@​perl.org; steve.tolkin@​fmr.com Subject​: Re​: [ID 20000522.002] Documentation for utime should be improved

On Wed\, Jun 07\, 2000 at 07​:25​:26PM -0700\, Yitzchak Scott-Thoennes wrote​:

This is a bug report for perl from steve.tolkin@​fmr.com\, generated with the help of perlbug 1.26 running under perl 5.00503.

Ideally touch would also be added to the perlfunc man page\, as a dummy entry\, just to refer to utime. A precedent for this has been established by including the non-existent function export.

Where? I don't see any such thing.

Steve may have meant import rather than export.

=item import

There is no builtin C\ function. It is just an ordinary method (subroutine) defined (or inherited) by modules that wish to export names to another module. The C\ function calls the C\ method for the package used. See also L\</use()>\, L\\, and L\.

I don't think that touch and import are similar cases\, however. import is not a builtin\, but it is part of the core.

Ronald

[p5pRT]

From @smpeters

[Steve.Tolkin@​fmr.com - Mon May 22 01​:39​:42 2000]​:

This is a bug report for perl from steve.tolkin@​fmr.com\, generated with the help of perlbug 1.26 running under perl 5.00503.

----------------------------------------------------------------- [Please enter your report here] The documentation for utime should be improved\, as follows​:

Please change the man page for the utime() function. It should add something like​: Certain file systems can only store the time with a granularity (precision) of 2 seconds. Some systems known to have this limitation are the FAT file system used in DOS and various Microsoft Windows file systems derived from it. This is a limitation of the file system\, not of utime.

Change perlfaq5 to have similar language\, instead of the current wording "doesn't work correctly with Win95/NT" which is both vague and imappropriately scary.

There was some discussion of this in news//comp.lang.perl.moderated under the subject Does utime work correctly on Windows NT perl? and date beginning 2000-05-19

In addition please add the words "utime" and "touch" to the *question* "How do I set a file's timestamp?" in perlfaq5.

The point is to allow the command "perldoc -q touch" to find this question and answer.
Perldoc -q only searches the text of the *question*.

In general adding one or two words to the the question that gives the answer is a usefull approach to other FAQ questions too. I spent a while searching for "touch" before I found utime by looking at the names of all the perl functions.

Ideally touch would also be added to the perlfunc man page\, as a dummy entry\, just to refer to utime. A precedent for this has been established by including the non-existent function export.

Steven Tolkin steve.tolkin@​fmr.com 2000-05-22 [Please do not change anything below this line] -----------------------------------------------------------------

My this is an old one. The below patch clarifies the FAT and HPFS filesystem issues\, and adds a mention of the touch example given in perlfunc to perlfaq5.

The original discussion is in http​://groups-beta.google.com/group/comp.lang.perl.moderated/browse_thread/thread/632ef5480ef3a636/f274aa3de5040965?q=Win32+utime+Perl&_done=%2Fgroups%3Fhl%3Den%26q%3DWin32+utime+Perl%26qt_s%3DSearch+Groups%26&_doneTitle=Back+to+Search&&d#f274aa3de5040965

Inline Patch

```diff --- perlfaq5.pod.orig Mon Dec 13 23:12:59 2004 +++ perlfaq5.pod Mon Dec 13 23:49:37 2004 @@ -684,9 +684,14 @@ Error checking is, as usual, left as an exercise for the reader. -Note that utime() currently doesn't work correctly with Win95/NT -ports. A bug has been reported. Check it carefully before using -utime() on those platforms. +The perldoc for utime also has an example that has the same +effect as touch(1) on files that I. + +Certain file systems have a limited ability to store the times +on a file at the expected level of precision. For example, the +FAT and HPFS filesystem are unable to create dates on files with +a finer granularity than two seconds. This is a limitation of +filesystems, not of utime(). =head2 How do I print to more than one file at once? ```

[p5pRT]

From @smpeters

[stmpeters - Mon Dec 13 21​:54​:10 2004]​:

[Steve.Tolkin@​fmr.com - Mon May 22 01​:39​:42 2000]​:

This is a bug report for perl from steve.tolkin@​fmr.com\, generated with the help of perlbug 1.26 running under perl 5.00503.

----------------------------------------------------------------- [Please enter your report here] The documentation for utime should be improved\, as follows​:

Please change the man page for the utime() function. It should add something like​: Certain file systems can only store the time with a granularity (precision) of 2 seconds. Some systems known to have this limitation are the FAT file system used in DOS and various Microsoft Windows file systems derived from it. This is a limitation of the file system\, not of utime.

Change perlfaq5 to have similar language\, instead of the current wording "doesn't work correctly with Win95/NT" which is both vague and imappropriately scary.

There was some discussion of this in news//comp.lang.perl.moderated under the subject Does utime work correctly on Windows NT perl? and date beginning 2000-05-19

In addition please add the words "utime" and "touch" to the *question* "How do I set a file's timestamp?" in perlfaq5.

The point is to allow the command "perldoc -q touch" to find this question and answer. Perldoc -q only searches the text of the *question*.

In general adding one or two words to the the question that gives the answer is a usefull approach to other FAQ questions too. I spent a while searching for "touch" before I found utime by looking at the names of all the perl functions.

Ideally touch would also be added to the perlfunc man page\, as a dummy entry\, just to refer to utime. A precedent for this has been established by including the non-existent function export.

Steven Tolkin steve.tolkin@​fmr.com 2000-05-22 [Please do not change anything below this line] -----------------------------------------------------------------

My\, this is an old one. The below patch clarifies the FAT and HPFS filesystem issues\, and adds a mention of the touch example given in perlfunc to perlfaq5.

The original discussion is in http​://groups- beta.google.com/group/comp.lang.perl.moderated/browse_thread/thread/632ef5480ef3a636/f274aa3de5040965?q=Win32+utime+Perl&_done=%2Fgroups%3Fhl%3Den%26q%3DWin32+utime+Perl%26qt_s%3DSearch+Groups%26&_doneTitle=Back+to+Search&&d#f274aa3de5040965

Inline Patch

```diff --- perlfaq5.pod.orig Mon Dec 13 23:12:59 2004 +++ perlfaq5.pod Mon Dec 13 23:49:37 2004 @@ -684,9 +684,14 @@ Error checking is, as usual, left as an exercise for the reader. -Note that utime() currently doesn't work correctly with Win95/NT -ports. A bug has been reported. Check it carefully before using -utime() on those platforms. +The perldoc for utime also has an example that has the same +effect as touch(1) on files that I. + +Certain file systems have a limited ability to store the times +on a file at the expected level of precision. For example, the +FAT and HPFS filesystem are unable to create dates on files with + a finer granularity than two seconds. This is a limitation of +filesystems, not of utime(). =head2 How do I print to more than one file at once? ```

[p5pRT]

From @tux

On Tue 14 Dec 2004 07​:29\, "Steve Peters via RT" \perlbug\-followup@&#8203;perl\.org wrote​:

My\, this is an old one. The below patch clarifies the FAT and HPFS filesystem issues\, and adds a mention of the touch example given in perlfunc to perlfaq5.

The original discussion is in http​://groups- beta.google.com/group/comp.lang.perl.moderated/browse_thread/thread/632ef5480ef3a636/f274aa3de5040965?q=Win32+utime+Perl&_done=%2Fgroups%3Fhl%3Den%26q%3DWin32+utime+Perl%26qt_s%3DSearch+Groups%26&_doneTitle=Back+to+Search&&d#f274aa3de5040965

--- perlfaq5.pod.orig Mon Dec 13 23​:12​:59 2004 +++ perlfaq5.pod Mon Dec 13 23​:49​:37 2004 @​@​ -684\,9 +684\,14 @​@​

Error checking is\, as usual\, left as an exercise for the reader.

-Note that utime() currently doesn't work correctly with Win95/NT -ports. A bug has been reported. Check it carefully before using -utime() on those platforms. +The perldoc for utime also has an example that has the same +effect as touch(1) on files that I\. + +Certain file systems have a limited ability to store the times +on a file at the expected level of precision. For example\, the +FAT and HPFS filesystem are unable to create dates on files with + a finer granularity than two seconds. This is a limitation of +filesystems\, not of utime().

=head2 How do I print to more than one file at once?

I removed the dangling space and added "the"​:

Change 23647 by merijn@​merijn-l1 on 2004/12/14 07​:51​:43

  Subject​: [perl #3274] [PATCH] Documentation for utime should be improved   Date​: 14 Dec 2004 06​:29​:23 -0000   From​: "Steve Peters via RT" \perlbug\-followup@&#8203;perl\.org   Message-ID​: \rt\-3\.0\.11\-3274\-103026\.2\.21000805211489@&#8203;perl\.org

Affected files ...

... //depot/perl/pod/perlfaq5.pod#58 edit

Differences ...

==== //depot/perl/pod/perlfaq5.pod#58 (text) ====

687\,689c687\,694 \< Note that utime() currently doesn't work correctly with Win95/NT \< ports. A bug has been reported. Check it carefully before using \< utime() on those platforms.

---

The perldoc for utime also has an example that has the same effect as touch(1) on files that I\.

Certain file systems have a limited ability to store the times on a file at the expected level of precision. For example\, the FAT and HPFS filesystem are unable to create dates on files with a finer granularity than two seconds. This is a limitation of the filesystems\, not of utime().

-- H.Merijn Brand Amsterdam Perl Mongers (http​://amsterdam.pm.org/) using perl-5.6.1\, 5.8.5\, & 5.9.x\, and 809 on HP-UX 10.20 & 11.00\, 11i\,   AIX 4.3\, AIX 5.2\, SuSE 9.1\, and Win2k. http​://www.cmve.net/~merijn/ http​://archives.develooper.com/daily-build@​perl.org/ perl-qa@​perl.org send smoke reports to​: smokers-reports@​perl.org\, QA​: http​://qa.perl.org

[p5pRT]

From @smpeters

[hmbrand - Tue Dec 14 00​:55​:09 2004]​:

On Tue 14 Dec 2004 07​:29\, "Steve Peters via RT" \<perlbug- followup@​perl.org> wrote​:

My\, this is an old one. The below patch clarifies the FAT and HPFS filesystem issues\, and adds a mention of the touch example given in perlfunc to perlfaq5.

The original discussion is in http​://groups-

beta.google.com/group/comp.lang.perl.moderated/browse_thread/thread/632ef5480ef3a636/f274aa3de5040965?q=Win32+utime+Perl&_done=%2Fgroups%3Fhl%3Den%26q%3DWin32+utime+Perl%26qt_s%3DSearch+Groups%26&_doneTitle=Back+to+Search&&d#f274aa3de5040965

--- perlfaq5.pod.orig Mon Dec 13 23​:12​:59 2004 +++ perlfaq5.pod Mon Dec 13 23​:49​:37 2004 @​@​ -684\,9 +684\,14 @​@​

Error checking is\, as usual\, left as an exercise for the reader.

-Note that utime() currently doesn't work correctly with Win95/NT -ports. A bug has been reported. Check it carefully before using -utime() on those platforms. +The perldoc for utime also has an example that has the same +effect as touch(1) on files that I\. + +Certain file systems have a limited ability to store the times +on a file at the expected level of precision. For example\, the +FAT and HPFS filesystem are unable to create dates on files with + a finer granularity than two seconds. This is a limitation of +filesystems\, not of utime().

=head2 How do I print to more than one file at once?

I removed the dangling space and added "the"​:

Change 23647 by merijn@​merijn-l1 on 2004/12/14 07​:51​:43

    Subject​: \[perl \#3274\] \[PATCH\] Documentation for utime should

be improved Date​: 14 Dec 2004 06​:29​:23 -0000 From​: "Steve Peters via RT" \perlbug\-followup@&#8203;perl\.org Message-ID​: \rt\-3\.0\.11\-3274\-103026\.2\.21000805211489@&#8203;perl\.org

Affected files ...

... //depot/perl/pod/perlfaq5.pod#58 edit

Differences ...

==== //depot/perl/pod/perlfaq5.pod#58 (text) ====

687\,689c687\,694 \< Note that utime() currently doesn't work correctly with Win95/NT \< ports. A bug has been reported. Check it carefully before using \< utime() on those platforms. ---

The perldoc for utime also has an example that has the same effect as touch(1) on files that I\.

Certain file systems have a limited ability to store the times on a file at the expected level of precision. For example\, the FAT and HPFS filesystem are unable to create dates on files with a finer granularity than two seconds. This is a limitation of the filesystems\, not of utime().

Applied as change #23647 as well as committed to the perlfaq cvs repository.

[p5pRT]

@smpeters - Status changed from 'open' to 'resolved'