X-Authentication-Warning: delorie.com: mail set sender to djgpp-bounces using -f From: "Rod Pemberton" Newsgroups: comp.os.msdos.djgpp Subject: Re: ambiguous man pages Date: Sat, 24 Aug 2013 04:24:48 -0400 Organization: Aioe.org NNTP Server Lines: 123 Message-ID: References: <3b166a82-36d9-4caa-acdf-dc37c382de00 AT googlegroups DOT com> NNTP-Posting-Host: CNsg4fVcCsvs3UaOgZtQCw.user.speranza.aioe.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii; format=flowed; delsp=yes Content-Transfer-Encoding: 7bit X-Complaints-To: abuse AT aioe DOT org User-Agent: Opera Mail/12.16 (Linux) X-Notice: Filtered by postfilter v. 0.8.2 Bytes: 5556 To: djgpp AT delorie DOT com DJ-Gateway: from newsgroup comp.os.msdos.djgpp Reply-To: djgpp AT delorie DOT com On Fri, 23 Aug 2013 22:36:53 -0400, Jim Michaels wrote: > www.delorie.com/djgpp/doc/libc/libc_538.html > needs clarification. > does this function allocate memory for the struct ptr? yes or no. > No. > the page states "Return Value:A pointer to a static structure which is > overwritten with each call." > > this is ambiguous. is the pointer overwritten, or is it the structure > overwritten with each call? > > [link] > localtime()'s internal 'struct tm' structure is filled for each call. The returned pointer from localtime() points to that internal structure. > does this function allocate memory for the struct ptr? yes or no. > No. > please clarify, thanks. I'm not sure what your C skill level is, so I'll respond as if you're just learning C. Please, don't take offense, if not. IMO, DJ's warped reply would confuse even a C expert... First, there are two 'struct tm' structures being used. One should be in declared and allocated in your code. The other is internal to localtime(). You should have no need to declare or use any pointers. Actually, the pointer returned by localtime() is (typically) not allocated either. Hopefully, you'll understand by the end of this post. There is a 'struct tm' structure which is internal to localtime() that is filled in by localtime(). localtime() returns a pointer to it's internal structure so that you may copy that structure to your structure. The return value of a procedure is allocated and free'd automatically. There is no need to concern yourself with the mechanism of this, although many C compilers use a register for it. The structure internal to localtime() may be statically allocated or dynamically allocated. It might be statically allocated and therefore constant, or it could be malloc'd and free'd on each call to localtime. This is up to the implementor of the compiler library. Their job is to make localtime() work correctly. I.e., you shouldn't make any assumptions about the pointer returned by localtime(), since you don't know how localtime() is implemented and it may vary from compiler to compiler. Obviously, the DJGPP libc.a reference says it's a static area for DJGPP. Remember, DJGPP does *not* use a GNU C library, like GLIBC, but one custom built for DOS. Harbison and Steele's, "C: A Reference Manual," says many C implementations also use a static data area shared by both localtime() and gmtime() procedures. Even so, you still shouldn't make assumptions about the returned pointer's value or about the memory allocation used for the data at that location. If localtime() is implemented correctly, this shouldn't concern you or affect your program in any way. According to Harbison and Steele's, "C: A Reference Manual," for early C, you had to copy structures element-by-element. You probably could've used memcpy() too. Later versions of C, allow assignment of one structure or union to another structure or union of compatible type. This means ANSI-C and ISO allow this, therefore DJGPP does too. I.e., you don't need to copy a structure or union (anymore). You can simply assign one to another to copy it, unlike early C. A typical example of how to use localtime(): /* declare and allocate space for 'struct tm' type */ /* it's named timestruct here */ struct tm timestruct; /* declare and allocate space for 'time_t' type */ /* it's named timeinteger here */ time_t timeinteger; /* assigned returned integer from time() to timeinteger */ timeinteger = time(NULL); /* pass pointer to timeinteger to be decoded by localtime */ /* pointer is obtained using the 'address-of' operator & */ /* dereference the pointer to the returned localtime struct */ /* dereference is done using the 'indirection' operator * */ /* copy the localtime struct to timestruct */ /* copying is performed via the assignment '=' operator */ /* -for structs and unions in ANSI C or later */ timestruct = *localtime(&timeinteger); As you can see from the four lines of C code, no pointers to a struct of type 'struct tm' were ever declared or allocated in that code. Technically, one typically isn't even allocated for the pointer returned by localtime() either, since many C compilers use a register for a procedure's return value. Memory must be allocated. Stack space, if memory-mapped by C or part of the C memory pool, must be allocated. Registers aren't memory mapped and are unallocated in the C context, although they may be in-use... The address-of operator likely provides the pointer to the allocated space of the declared 'struct tm' structure used by localtime(). HTH, Rod Pemberton