std-unix@ut-sally.UUCP (Moderator, John Quarterman) (09/29/86)
There are several decisions needed regarding timezones and 1003.1:
Which proposal should be accepted (P.55 or the one forthcoming from HP)?
If P.55:
Accept settz 4.5.3?
Add 4.5.4 or incorporate third paragraph in 4.5.3?
Details of Errors and References.
Suggested Appendices:
Olsen's implementation?
List of names of timezones?
The rest of this article is the text of Proposal 55.
IEEE 1003.1 P.55:
Time Zone Proposal based on work by Robert Elz and Arthur Olsen.
Submitted by John S. Quarterman. Proposal number assigned 19 Sept. 1986.
Add 4.5.3 and 4.5.4 to the standard and perhaps also
document Arthur Olsen's implementation in an Appendix.
Note that all of 4.5.4 except the last paragraph of 4.5.4.2, the last
sentence of 4.5.4.3, and all of 4.5.4.4 and 4.5.4.5, is intended to
track X3J11. I.e., the purpose of 4.5.4 is to constrain ctime() and
localtime() further than X3J11, not to change what X3J11 says about them.
% is used to indicate the section sign. Italics are implied in the
normal format of the POSIX document.
4.5.3 Set Local Time Conversion
Function: settz()
4.5.3.1 Synopsis
int settz(p)
char *p;
4.5.3.2 Description
The settz() function determines the conversion from GMT
of the local times returned by localtime() and ctime().
When called with a NULL pointer argument (p==0), settz
shall select the appropriate local time conversion for the
location of the host machine on which the call is executed.
When called with a null string (p!=0 && *p=='\0'), settz
shall select no conversion for localtime, making localtime()
and gmtime() equivalent and ctime() and asctime(gmtime())
equivalent. When called with a non-null string (p!=0 && *p!='\0'),
settz may set the conversion according to that string.
The format of the string and the conversions it may specify
are implementation specific. If an implementation accepts
non-null string arguments to settz, the implementation
should allow users to define their own conversions
rather than restricting conversions to a standard set.
If settz is called with a string for which the implementation
can not find a conversion, settz shall return -1, but the
conversion it sets is implementation defined and may be one of
GMT, the executing machine's local time, or local time for
the area where the implementation was performed.
4.5.3.3 Returns
Upon successful completion, settz() returns 0, otherwise -1,
and errno is set to indicate the error.
4.5.3.4 Errors
If the function returns -1 the value stored in errno may be
interpreted as follows:
[EFAULT] The argument p points outside the process's allocated
addresss space.
4.5.3.5 References
time() %4.5.1, localtime(), ctime() %4.5.4.
4.5.4 Get Local Time
Functions: localtime(), ctime()
4.5.4.1 Synopsis
#include <time.h>
struct tm *localtime(timer)
char *ctime(timer)
time_t *timer;
4.5.4.2 Description
The localtime() function converts the calendar time pointed to
by timer to local time in the form of a string. It is equivalent to
asctime(localtime(timer))
The local time conversion is specified by a call on settz().
If localtime() or ctime() is called and settz() has not been called
since the last exec(), the localtime() or ctime() call shall call
settz(getenv("TZ")) before performing the local time conversion.
The local time conversion should be accurate for all times
from the base time of the time() function up to the time
the call is made. Future times should be converted as accurately
as possible with available political information. Daylight savings
time should be taken into account in both cases.
4.5.4.3 Returns
The localtime() function returns a pointer to that object.
The ctime() function returns the pointer returned by the
asctime() function with that broken-down time as argument.
On unsuccessful completion of either function, a NULL pointer
shall be returned and errno is set to indicate the error.
4.5.4.4 Errors
If either function returns a NULL pointer the value stored in
errno may be interpreted as follows:
[EFAULT] The argument points outside the process's allocated
address space.
4.5.4.5 References
time() %4.5.1, settz() %4.5.3.
Volume-Number: Volume 7, Number 8std-unix@ut-sally.UUCP (Moderator, John Quarterman) (09/30/86)
From: seismo!elsie!ado (Arthur Olson)
Date: Mon, 29 Sep 86 22:46:41 EDT
A few words regarding the "P.55" time zone proposal.
One thing it lacks is a way of determining the "time zone abbreviation"
("EST" or "EDT" or "EWT", for example) to be used with a particular combination
of time and time zone. One approach is to declare a global variable such as
char * tz_abbr;
and have "localtime" set it to point to the abbreviation for the converted time.
Alternately, some folks have suggested adding either a character pointer or a
character array to the "struct tm" that "localtime" returns as a way of
recording the abbreviation. The approach used isn't too important;
standardizing the approach is. (Avoiding changes to the "struct tm" structure
would be desirable if there are applications that have stored such structures
in files. I don't know of--and can't imagine--applications that do so.)
If the standard *does* end up telling how a caller of localtime can learn the
abbreviation for the converted time, then a change may be needed in the
passage reading
> When called with a null string (p!=0 && *p=='\0'), settz
> shall select no conversion for localtime, making localtime()
> and gmtime() equivalent and ctime() and asctime(gmtime())
> equivalent.
If, for example, "localtime" sets "tz_abbr" as a side effect, but "gmtime"
doesn't, then calling "localtime" and calling "gmtime" can never be equivalent.
It may be simplest to just leave the settz("") case out of the standard
entirely--any application programmer who's interested in getting GMT can
just call gmtime() directly. (The settz("") case is actually a bone to throw
to speedsters who don't want "ls" to get time conversion information from
disk; while this has some value, the value may well be too small to warrant
standardization.) But having settz((char *) 0) set things for local time
(regardless, for example, of the state of the environment variable "TZ")
provides a capability that's important to programs such as uucp;
the behavior of settz((char *) 0) *should*, I believe, be documented.
Concretely: I'd suggest this shortening of section 4.5.3.2:
4.5.3.2 Description
The settz() function determines the conversion from GMT
of the local times returned by localtime() and ctime().
When called with a null pointer argument (p==0), settz
shall select the appropriate local time conversion for the
location of the host machine on which the call is executed.
When called with a non-null pointer argument (p!=0),
settz may set the conversion according to that string...
And, perhaps, an addition along these lines to 4.5.4.3 (or wherever):
As a side effect, both ctime and localtime set the global character
pointer tz_abbr to point to the time zone abbreviation for the
converted time and time zone.
--
UUCP: ..decvax!seismo!elsie!ado ARPA: elsie!ado@seismo.ARPA
DEC, VAX, Elsie & Ado are Digital, Borden & Ampex trademarks.
Volume-Number: Volume 7, Number 10std-unix@ut-sally.UUCP (Guest Moderator, John B. Chambers) (10/03/86)
From decvax!ittatc!bunker!garys@seismo.UUCP Thu Oct 2 16:11:22 1986 Date: Wed, 1 Oct 86 11:04:08 edt Return-Path: <ittatc!bunker!garys> Message-Id: <8610011504.AA04301@ittatc.UUCP> To: std-unix@ut-sally.UUCP Subject: Re: IEEE 1003.1 P.55 Newsgroups: mod.std.unix In-Reply-To: <5836@ut-sally.UUCP> Organization: Bunker Ramo, Trumbull CT In article <5836@ut-sally.UUCP> you write: >If settz is called with a string for which the implementation >can not find a conversion, settz shall return -1... Under section 4.5.3.4, the appropriate value for errno is not specified for this case. See suggested additional wording, below. >4.5.3.4 Errors > If the function returns -1 the value stored in errno may be >interpreted as follows: I suggest the following change in wording: -[EFAULT] The argument p points outside the process's allocated - address space. +[EFAULT] The argument p does not point to a readable string. This covers the case where the beginning of the string is within the process's address space, but the end is not. I suggest the following additional wording: +[EINVAL] The argument p points to a string for which the + implementation could not find a conversion. >4.5.4 Get Local Time >Functions: localtime(), ctime() > >4.5.4.1 Synopsis > #include <time.h> It is not clear that the type of 'timer' specified for 'ctime' also applies to 'localtime'. I suggest the following additional wording: > struct tm *localtime(timer) + time_t *timer; + > char *ctime(timer) > time_t *timer; >4.5.4.3 Returns The description of ctime's return value specifies not only the return value of ctime, but also how ctime should be coded (i.e., 'ctime' must call 'asctime'). I suggest the following change in wording: - The ctime() function returns the pointer returned by the -asctime() function with that broken-down time as argument. + The ctime() function returns a pointer to a string containing +the time, converted to the same format produced by 'asctime'. >4.5.4.4 Errors I suggest the following change in wording: -[EFAULT] The argument p points outside the process's allocated - address space. +[EFAULT] The argument p does not point to a readable object of + type time_t. This covers the cases where the first byte of time_t is in the address space, but the last byte isn't, and where the pointer is not properly aligned. I suggest the following additional wording: +[EINVAL] The argument points to an object which does not contain + a valid time_t value. Gary Samuelson Volume-Number: Volume 7, Number 13
std-unix@ut-sally.UUCP (12/10/86)
[ This is a reposting of P.55, the P1003.1 Timezones proposal,
due to recent interest coinciding with the meeting of P1003
going on this week in Atlantic City. -mod ]
From: std-unix%ut-sally.UUCP@sally.utexas.edu (Moderator, John Quarterman)
Date: 29 Sep 86 19:14:18 GMT
There are several decisions needed regarding timezones and 1003.1:
Which proposal should be accepted (P.55 or the one forthcoming from HP)?
If P.55:
Accept settz 4.5.3?
Add 4.5.4 or incorporate third paragraph in 4.5.3?
Details of Errors and References.
Suggested Appendices:
Olsen's implementation?
List of names of timezones?
The rest of this article is the text of Proposal 55.
IEEE 1003.1 P.55:
Time Zone Proposal based on work by Robert Elz and Arthur Olsen.
Submitted by John S. Quarterman. Proposal number assigned 19 Sept. 1986.
Add 4.5.3 and 4.5.4 to the standard and perhaps also
document Arthur Olsen's implementation in an Appendix.
Note that all of 4.5.4 except the last paragraph of 4.5.4.2, the last
sentence of 4.5.4.3, and all of 4.5.4.4 and 4.5.4.5, is intended to
track X3J11. I.e., the purpose of 4.5.4 is to constrain ctime() and
localtime() further than X3J11, not to change what X3J11 says about them.
% is used to indicate the section sign. Italics are implied in the
normal format of the POSIX document.
4.5.3 Set Local Time Conversion
Function: settz()
4.5.3.1 Synopsis
int settz(p)
char *p;
4.5.3.2 Description
The settz() function determines the conversion from GMT
of the local times returned by localtime() and ctime().
When called with a NULL pointer argument (p==0), settz
shall select the appropriate local time conversion for the
location of the host machine on which the call is executed.
When called with a null string (p!=0 && *p=='\0'), settz
shall select no conversion for localtime, making localtime()
and gmtime() equivalent and ctime() and asctime(gmtime())
equivalent. When called with a non-null string (p!=0 && *p!='\0'),
settz may set the conversion according to that string.
The format of the string and the conversions it may specify
are implementation specific. If an implementation accepts
non-null string arguments to settz, the implementation
should allow users to define their own conversions
rather than restricting conversions to a standard set.
If settz is called with a string for which the implementation
can not find a conversion, settz shall return -1, but the
conversion it sets is implementation defined and may be one of
GMT, the executing machine's local time, or local time for
the area where the implementation was performed.
4.5.3.3 Returns
Upon successful completion, settz() returns 0, otherwise -1,
and errno is set to indicate the error.
4.5.3.4 Errors
If the function returns -1 the value stored in errno may be
interpreted as follows:
[EFAULT] The argument p points outside the process's allocated
addresss space.
4.5.3.5 References
time() %4.5.1, localtime(), ctime() %4.5.4.
4.5.4 Get Local Time
Functions: localtime(), ctime()
4.5.4.1 Synopsis
#include <time.h>
struct tm *localtime(timer)
char *ctime(timer)
time_t *timer;
4.5.4.2 Description
The localtime() function converts the calendar time pointed to
by timer to local time in the form of a string. It is equivalent to
asctime(localtime(timer))
The local time conversion is specified by a call on settz().
If localtime() or ctime() is called and settz() has not been called
since the last exec(), the localtime() or ctime() call shall call
settz(getenv("TZ")) before performing the local time conversion.
The local time conversion should be accurate for all times
from the base time of the time() function up to the time
the call is made. Future times should be converted as accurately
as possible with available political information. Daylight savings
time should be taken into account in both cases.
4.5.4.3 Returns
The localtime() function returns a pointer to that object.
The ctime() function returns the pointer returned by the
asctime() function with that broken-down time as argument.
On unsuccessful completion of either function, a NULL pointer
shall be returned and errno is set to indicate the error.
4.5.4.4 Errors
If either function returns a NULL pointer the value stored in
errno may be interpreted as follows:
[EFAULT] The argument points outside the process's allocated
address space.
4.5.4.5 References
time() %4.5.1, settz() %4.5.3.
Volume-Number: Volume 7, Number 8
Volume-Number: Volume 8, Number 64std-unix@ut-sally.UUCP (12/13/86)
From: seismo!gatech!emory!arnold@sally.utexas.edu (Arnold D. Robbins {EUCC})
Date: Fri, 12 Dec 86 13:36:36 EST
Organization: Math & Computer Science, Emory University, Atlanta
Shouldn't there be some indication in errno that no conversion
was found [ by settz -mod ]? Otherwise, how is one's code supposed to know
that the string passed to settz() was valid and settz() couldn't find a
conversion? Both return -1!
[ Maybe EINVAL? -mod ]
>4.5.4.2 Description
> The localtime() function converts the calendar time pointed to
^^^^^^^^^^^
I think that this should be 'ctime', as that is the functionality
desribed by the next two lines:
>by timer to local time in the form of a string. It is equivalent to
> asctime(localtime(timer))
Otherwise, the proposal looks good to me!
---
Arnold Robbins
CSNET: arnold@emory BITNET: arnold@emoryu1
ARPA: arnold%emory.csnet@csnet-relay.arpa
UUCP: { akgua, decvax, gatech, sb1, sb6, sunatl }!emory!arnold
Volume-Number: Volume 8, Number 66