James E Keenan wrote:
Status of efforts in cfunctionsdocs branch:
1. Deleted two files and some related code per comments from Andy
Dougherty.
2. Made what I thought were reasonable POD corrections to
compilers/pirc/src/pircapi.c.
3. Provided at least minimal documentation for remaining C functions.
Can we get some eyeballs on the attached patch? If it's satisfactory
(with or without content modifications), then I can merge the
cfunctionsdocs into trunk. From that point forward, any failures in
t/codingstd/c_function_docs.t will represent new C functions added to
the repository without documentation.
Thank you very much.
kid51
Index: src/string/charset/iso-8859-1.c
===================================================================
--- src/string/charset/iso-8859-1.c (.../trunk) (revision 47551)
+++ src/string/charset/iso-8859-1.c (.../branches/cfunctionsdocs)
(revision 47869)
@@ -541,6 +541,8 @@
=item C<static INTVAL is_cclass(PARROT_INTERP, INTVAL flags, const STRING *src,
UINTVAL offset)>
+Returns Boolean.
+
=cut
*/
@@ -591,6 +593,8 @@
=item C<static INTVAL find_not_cclass(PARROT_INTERP, INTVAL flags, const STRING
*src, UINTVAL offset, UINTVAL count)>
+Returns C<INTVAL>.
+
=cut
*/
Index: src/string/charset/binary.c
===================================================================
--- src/string/charset/binary.c (.../trunk) (revision 47551)
+++ src/string/charset/binary.c (.../branches/cfunctionsdocs) (revision 47869)
@@ -407,6 +407,8 @@
=item C<static INTVAL is_cclass(PARROT_INTERP, INTVAL flags, const STRING *src,
UINTVAL offset)>
+Returns Boolean.
+
=cut
*/
@@ -423,6 +425,8 @@
=item C<static INTVAL find_cclass(PARROT_INTERP, INTVAL flags, const STRING
*src, UINTVAL offset, UINTVAL count)>
+Find a character in the given character class.
+
=cut
*/
@@ -440,6 +444,8 @@
=item C<static INTVAL find_not_cclass(PARROT_INTERP, INTVAL flags, const STRING
*src, UINTVAL offset, UINTVAL count)>
+Returns C<INTVAL>.
+
=cut
*/
@@ -456,6 +462,9 @@
=item C<static STRING * string_from_codepoint(PARROT_INTERP, UINTVAL
codepoint)>
+Creates a new STRING object from a single codepoint C<codepoint>. Returns
+the new STRING.
+
=cut
*/
Index: src/string/charset/unicode.c
===================================================================
--- src/string/charset/unicode.c (.../trunk) (revision 47551)
+++ src/string/charset/unicode.c (.../branches/cfunctionsdocs)
(revision 47869)
@@ -738,6 +738,8 @@
=item C<static int u_iscclass(PARROT_INTERP, UINTVAL codepoint, INTVAL flags)>
+Returns Boolean.
+
=cut
*/
@@ -834,6 +836,8 @@
=item C<static INTVAL is_cclass(PARROT_INTERP, INTVAL flags, const STRING *src,
UINTVAL offset)>
+Returns Boolean.
+
=cut
*/
@@ -861,6 +865,8 @@
=item C<static INTVAL find_cclass(PARROT_INTERP, INTVAL flags, const STRING
*src, UINTVAL offset, UINTVAL count)>
+Find a character in the given character class.
+
=cut
*/
@@ -901,6 +907,8 @@
=item C<static INTVAL find_not_cclass(PARROT_INTERP, INTVAL flags, const STRING
*src, UINTVAL offset, UINTVAL count)>
+Returns C<INTVAL>.
+
=cut
*/
Index: src/string/charset/ascii.c
===================================================================
--- src/string/charset/ascii.c (.../trunk) (revision 47551)
+++ src/string/charset/ascii.c (.../branches/cfunctionsdocs) (revision 47869)
@@ -678,6 +678,8 @@
=item C<static INTVAL is_cclass(PARROT_INTERP, INTVAL flags, const STRING *src,
UINTVAL offset)>
+Returns Boolean.
+
=cut
*/
@@ -729,6 +731,8 @@
=item C<static INTVAL find_not_cclass(PARROT_INTERP, INTVAL flags, const STRING
*src, UINTVAL offset, UINTVAL count)>
+Returns C<INTVAL>.
+
=cut
*/
@@ -883,6 +887,14 @@
}
/*
+
+=back
+
+=cut
+
+*/
+
+/*
* Local variables:
* c-file-style: "parrot"
* End:
Index: src/io/api.c
===================================================================
--- src/io/api.c (.../trunk) (revision 47551)
+++ src/io/api.c (.../branches/cfunctionsdocs) (revision 47869)
@@ -20,8 +20,8 @@
is used in Parrot ops.
TODO: Where possible, extract some of the filehandle-related details into
-src/io/filehandle.c, and extract the stringhandle details into
-src/io/io_string.c.
+F<src/io/filehandle.c>, and extract the stringhandle details into
+a new F<src/io/io_string.c>.
=cut
Index: MANIFEST
===================================================================
--- MANIFEST (.../trunk) (revision 47551)
+++ MANIFEST (.../branches/cfunctionsdocs) (revision 47869)
@@ -1,7 +1,7 @@
# ex: set ro:
# $Id$
#
-# generated by tools/dev/mk_manifest_and_skip.pl Wed Jun 9 14:23:50 2010 UT
+# generated by tools/dev/mk_manifest_and_skip.pl Sat Jun 26 13:30:18 2010 UT
#
# See below for documentation on the format of this file.
#
@@ -278,7 +278,6 @@
config/gen/platform/cygwin/math.c []
config/gen/platform/darwin/begin.c []
config/gen/platform/darwin/hires_timer.c []
-config/gen/platform/darwin/memalign.c []
config/gen/platform/generic/dl.c []
config/gen/platform/generic/dl.h []
config/gen/platform/generic/env.c []
@@ -288,7 +287,6 @@
config/gen/platform/generic/itimer.c []
config/gen/platform/generic/math.c []
config/gen/platform/generic/math.h []
-config/gen/platform/generic/memalign.c []
config/gen/platform/generic/memexec.c []
config/gen/platform/generic/platform_limits.h []
config/gen/platform/generic/signal.c []
Index: compilers/pirc/src/pircapi.c
===================================================================
--- compilers/pirc/src/pircapi.c (.../trunk) (revision 47551)
+++ compilers/pirc/src/pircapi.c (.../branches/cfunctionsdocs)
(revision 47869)
@@ -17,7 +17,10 @@
/* HEADERIZER BEGIN: static */
/* Don't modify between HEADERIZER BEGIN / HEADERIZER END. Your changes will
be lost. */
+/* Don't modify between HEADERIZER BEGIN / HEADERIZER END. Your changes will
be lost. */
+/* HEADERIZER END: static */
+
/*
=head1 DESCRIPTION
@@ -72,17 +75,15 @@
=item C<void parse_file(PARROT_INTERP, int flexdebug, FILE *infile, char *
const
filename, int flags, int thr_id, unsigned macro_size, char * const outputfile)>
-=cut
-
This will be the proper declaration after testing for thread-safety:
void parse_file(int flexdebug, FILE *infile, char * const filename, int flags,
char * const outputfile)
+=cut
+
*/
-
-
void
parse_file(PARROT_INTERP, int flexdebug, ARGIN(FILE *infile),
ARGIN(char * const filename), int flags,
@@ -260,6 +261,8 @@
=item C<PackFile_ByteCode * pirc_compile_file(PARROT_INTERP, const char
*filename, STRING **error_message)>
+Returns NULL.
+
=cut
*/
@@ -274,9 +277,7 @@
}
-/* HEADERIZER END: static */
-
/*
=back
Index: t/codingstd/c_function_docs.t
===================================================================
--- t/codingstd/c_function_docs.t (.../trunk) (revision 47551)
+++ t/codingstd/c_function_docs.t (.../branches/cfunctionsdocs)
(revision 47869)
@@ -91,28 +91,6 @@
}
__DATA__
-compilers/pirc/src/pircapi.c
-config/gen/platform/ansi/dl.c
-config/gen/platform/ansi/exec.c
-config/gen/platform/ansi/time.c
-config/gen/platform/darwin/memalign.c
-config/gen/platform/generic/dl.c
-config/gen/platform/generic/exec.c
-config/gen/platform/generic/math.c
-config/gen/platform/generic/memalign.c
-config/gen/platform/generic/stat.c
-config/gen/platform/generic/time.c
-config/gen/platform/netbsd/math.c
-config/gen/platform/openbsd/math.c
-config/gen/platform/solaris/math.c
-config/gen/platform/solaris/time.c
-examples/compilers/japhc.c
-src/gc/generational_ms.c
-src/io/io_string.c
-src/string/charset/ascii.c
-src/string/charset/binary.c
-src/string/charset/iso-8859-1.c
-src/string/charset/unicode.c
# Local Variables:
# mode: cperl
Index: config/gen/platform.pm
===================================================================
--- config/gen/platform.pm (.../trunk) (revision 47551)
+++ config/gen/platform.pm (.../branches/cfunctionsdocs) (revision 47869)
@@ -191,7 +191,6 @@
dl.c
stat.c
math.c
- memalign.c
signal.c
itimer.c
memexec.c
Index: config/gen/makefiles/root.in
===================================================================
--- config/gen/makefiles/root.in (.../trunk) (revision 47551)
+++ config/gen/makefiles/root.in (.../branches/cfunctionsdocs)
(revision 47869)
@@ -1798,7 +1798,7 @@
manifest_tests :
$(PERL) t/harness $(MANIFEST_TEST_FILES)
-examples_tests :
+examples_tests : test_prep
$(PERL) t/harness $(EXAMPLES_TEST_FILES)
# benchmark tests
Index: config/gen/platform/netbsd/math.c
===================================================================
--- config/gen/platform/netbsd/math.c (.../trunk) (revision 47551)
+++ config/gen/platform/netbsd/math.c (.../branches/cfunctionsdocs)
(revision 47869)
@@ -1,7 +1,7 @@
/* $Id$ */
/*
- * Copyright (C) 2006-2007, Parrot Foundation.
+ * Copyright (C) 2006-2010, Parrot Foundation.
*/
/*
@@ -12,7 +12,7 @@
=head1 DESCRIPTION
-math stuff
+Mathematical functions.
=head2 Functions
@@ -29,7 +29,7 @@
=item C<extern int Parrot_signbit(double x)>
-return true if the Numval has a negative sign.
+Return true if the Numval has a negative sign.
This is mostly for handling the -0.0 case.
=cut
@@ -57,6 +57,8 @@
=item C<int Parrot_signbit_l(long double x)>
+Like C<Parrot_signbit()>, only taking long double instead of double.
+
=cut
*/
Index: config/gen/platform/darwin/memalign.c
===================================================================
--- config/gen/platform/darwin/memalign.c (.../trunk) (revision 47551)
+++ config/gen/platform/darwin/memalign.c (.../branches/cfunctionsdocs)
(revision 47869)
@@ -1,201 +0,0 @@
-/*
- * $Id$
- * Copyright (C) 2007-2008, Parrot Foundation.
- */
-
-/*
-
-=head1 NAME
-
-memalign.c
-
-=head1 DESCRIPTION
-
-memalign related stuff
-
-=head2 Functions
-
-=over 4
-
-=cut
-
-*/
-
-#include <mach/vm_map.h>
-#include <mach/mach_init.h>
-
-/*
-
-=item C<static unsigned long log2int(unsigned long x)>
-
-=cut
-
-*/
-
-static unsigned long log2int(unsigned long x) {
- return (x < 2) ? 0 : log2int(x >> 1) + 1;
-}
-
-/*
-
-=item C<static unsigned long roundDownPowerOf2(unsigned long x)>
-
-=cut
-
-*/
-
-static unsigned long roundDownPowerOf2(unsigned long x) {
- return (1 << log2int(x));
-}
-
-/*
-
-=item C<static unsigned long roundUpPowerOf2(unsigned long x)>
-
-=cut
-
-*/
-
-static unsigned long roundUpPowerOf2(unsigned long x)
-{
- static unsigned long one = 1;
- unsigned long log2Int = log2int(x);
-
- return ((one << log2Int) == x) ? x : (one << (log2Int + 1));
-}
-
-/*
-
-=item C<static unsigned long roundUpToPageBoundary(unsigned long x)>
-
-=cut
-
-*/
-
-static unsigned long roundUpToPageBoundary(unsigned long x)
-{
- unsigned long roundedDown = trunc_page(x);
-
- return (roundedDown == x) ? x : (roundedDown + vm_page_size);
-}
-
-typedef struct _memalign_marker_t {
- vm_address_t start;
- vm_size_t size;
-} memalign_marker_t;
-
-/*
-
-=item C<void * Parrot_memalign(size_t align, size_t size)>
-
-=cut
-
-*/
-
-void *
-Parrot_memalign(size_t align, size_t size)
-{
- size_t effectiveAlign = align;
- size_t padding = 0;
- size_t amountToAllocate = 0;
-
- if (effectiveAlign < sizeof (void *))
- effectiveAlign = roundUpPowerOf2(sizeof (void *));
- else
- effectiveAlign = roundUpPowerOf2(effectiveAlign);
-
- if (effectiveAlign < sizeof (memalign_marker_t))
- padding = sizeof (memalign_marker_t);
- else
- padding = effectiveAlign;
-
- amountToAllocate = roundUpToPageBoundary(size + padding);
-
- {
- vm_address_t p = (vm_address_t)NULL;
- kern_return_t status = vm_allocate(mach_task_self(), &p,
- amountToAllocate, 1);
-
- if (status != KERN_SUCCESS)
- return NULL;
- else {
- vm_size_t logEffectiveAlign = log2int(effectiveAlign);
- vm_address_t lowestAvaliableAddress =
- p + sizeof (memalign_marker_t);
- vm_address_t roundedDownAddress =
- ((lowestAvaliableAddress >> logEffectiveAlign)
- << logEffectiveAlign);
- vm_address_t returnAddress =
- (roundedDownAddress == lowestAvaliableAddress)
- ? lowestAvaliableAddress
- : (roundedDownAddress + effectiveAlign);
- vm_address_t firstUnneededPage = 0;
-
- memalign_marker_t *marker =
- (memalign_marker_t *)returnAddress - 1;
-
- /* lowest address used, then round down to vm_page boundary */
- vm_address_t usedPageBase = trunc_page((vm_address_t)marker);
- marker->start = usedPageBase;
- marker->size = returnAddress + size - usedPageBase;
-
- if (usedPageBase > p) {
- status = vm_deallocate(mach_task_self(), p, usedPageBase - p);
-
- if (status != KERN_SUCCESS)
- fprintf(stderr, "Parrot_memalign(%zx, %zx) failed "
- "to deallocate extra header space.\n",
- align, size);
- }
-
- firstUnneededPage = roundUpToPageBoundary(returnAddress + size);
-
- if (firstUnneededPage < p + amountToAllocate) {
- status = vm_deallocate(mach_task_self(), firstUnneededPage,
- p + amountToAllocate - firstUnneededPage);
-
- if (status != KERN_SUCCESS) {
- fprintf(stderr, "Parrot_memalign(%zx, %zx) failed "
- "to deallocate extra footer space.\n",
- align, size);
- }
- }
-
- return (void *)returnAddress;
- }
- }
-}
-
-/*
-
-=item C<void Parrot_free_memalign(void *p)>
-
-=cut
-
-*/
-
-void
-Parrot_free_memalign(void *p)
-{
- memalign_marker_t *marker = (memalign_marker_t *)p - 1;
- kern_return_t status = vm_deallocate(mach_task_self(),
- marker->start, marker->size);
-
- if (status != KERN_SUCCESS)
- fprintf(stderr, "Parrot_free_memalign(%p) failed!\n", p);
-}
-
-/*
-
-=back
-
-=cut
-
-*/
-
-/*
- * Local variables:
- * c-file-style: "parrot"
- * End:
- * vim: expandtab shiftwidth=4:
- */
Index: config/gen/platform/ansi/time.c
===================================================================
--- config/gen/platform/ansi/time.c (.../trunk) (revision 47551)
+++ config/gen/platform/ansi/time.c (.../branches/cfunctionsdocs)
(revision 47869)
@@ -1,6 +1,6 @@
/*
* $Id$
- * Copyright (C) 2007, Parrot Foundation.
+ * Copyright (C) 2007-2010, Parrot Foundation.
*/
/*
@@ -27,6 +27,8 @@
=item C<INTVAL Parrot_intval_time(void)>
+Parrot wrapper around standard library C<time()> function, returning an INTVAL.
+
=cut
*/
@@ -42,6 +44,9 @@
=item C<FLOATVAL Parrot_floatval_time(void)>
+Note: We are unable to provide this level of precision under ANSI-C, so we
+just fall back to intval time for this.
+
=cut
*/
@@ -49,8 +54,6 @@
FLOATVAL
Parrot_floatval_time(void)
{
- /* unable to provide this level of precision under ANSI-C, so just fall
- back to intval time for this. */
Parrot_warn(NULL, PARROT_WARNINGS_PLATFORM_FLAG, "Parrot_floatval_time not
accurate");
return (FLOATVAL)Parrot_intval_time();
}
Index: config/gen/platform/ansi/dl.c
===================================================================
--- config/gen/platform/ansi/dl.c (.../trunk) (revision 47551)
+++ config/gen/platform/ansi/dl.c (.../branches/cfunctionsdocs)
(revision 47869)
@@ -1,6 +1,6 @@
/*
* $Id$
- * Copyright (C) 2007, Parrot Foundation.
+ * Copyright (C) 2007-2010, Parrot Foundation.
*/
/*
@@ -11,21 +11,17 @@
=head1 DESCRIPTION
-Dynlib stuff. (Currently, just placeholders.)
+Parrot functions -- B<none yet implemented> -- which wrap around standard
+library functions for handling dynamic libraries.
=head2 Functions
=over 4
-=cut
+=item C<void * Parrot_dlopen(const char *filename, Parrot_dlopen_flags flags)>
-*/
+Parrot wrapper around C<dlopen>. B<Not yet implemented.>
-/*
-
-=item C<void * Parrot_dlopen(const char *filename, SHIM(Parrot_dlopen_flags
-flags)>
-
=cut
*/
@@ -42,6 +38,8 @@
=item C<const char * Parrot_dlerror(void)>
+Parrot wrapper around C<dlerror>. B<Not yet implemented.>
+
=cut
*/
@@ -57,6 +55,8 @@
=item C<void * Parrot_dlsym(void *handle, const char *symbol)>
+Parrot wrapper around C<dlsym>. B<Not yet implemented.>
+
=cut
*/
@@ -73,6 +73,8 @@
=item C<int Parrot_dlclose(void *handle)>
+Parrot wrapper around C<dlclose>. B<Not yet implemented.>
+
=cut
*/
Index: config/gen/platform/ansi/exec.c
===================================================================
--- config/gen/platform/ansi/exec.c (.../trunk) (revision 47551)
+++ config/gen/platform/ansi/exec.c (.../branches/cfunctionsdocs)
(revision 47869)
@@ -1,6 +1,6 @@
/*
* $Id$
- * Copyright (C) 2004-2008, Parrot Foundation.
+ * Copyright (C) 2004-2010, Parrot Foundation.
*/
/*
@@ -25,7 +25,7 @@
=item C<INTVAL Parrot_Run_OS_Command(PARROT_INTERP, STRING *command)>
-Spawn a subprocess
+B<Not yet implemented on this platform.> Spawn a subprocess.
=cut
@@ -43,6 +43,8 @@
=item C<INTVAL Parrot_Run_OS_Command_Argv(PARROT_INTERP, PMC *cmdargs)>
+B<Not yet implemented on this platform.>
+
=cut
*/
Index: config/gen/platform/openbsd/math.c
===================================================================
--- config/gen/platform/openbsd/math.c (.../trunk) (revision 47551)
+++ config/gen/platform/openbsd/math.c (.../branches/cfunctionsdocs)
(revision 47869)
@@ -1,6 +1,6 @@
/*
* $Id$
- * Copyright (C) 2006-2007, Parrot Foundation.
+ * Copyright (C) 2006-2010, Parrot Foundation.
*/
/*
@@ -11,7 +11,7 @@
=head1 DESCRIPTION
-math stuff
+Mathematical functions.
=head2 Functions
@@ -37,7 +37,7 @@
=item C<extern int Parrot_signbit(double x)>
-return true if the Numval has a negative sign.
+Return true if the Numval has a negative sign.
This is mostly for handling the -0.0 case.
=cut
@@ -65,6 +65,8 @@
=item C<int Parrot_signbit_l(long double x)>
+Like C<Parrot_signbit()>, only taking long double instead of double.
+
=cut
*/
Index: config/gen/platform/generic/memalign.c
===================================================================
--- config/gen/platform/generic/memalign.c (.../trunk) (revision 47551)
+++ config/gen/platform/generic/memalign.c (.../branches/cfunctionsdocs)
(revision 47869)
@@ -1,94 +0,0 @@
-/*
- * $Id$
- * Copyright (C) 2004-2006, Parrot Foundation.
- */
-
-/*
-
-=head1 NAME
-
-config/gen/platform/generic/memalign.c
-
-=head1 DESCRIPTION
-
-memalign related stuff
-
-=head2 Functions
-
-=over 4
-
-=cut
-
-*/
-
-#if defined(PARROT_HAS_POSIX_MEMALIGN)
-# include <stdlib.h>
-
-/*
-
-=item C<void * Parrot_memalign(size_t align, size_t size)>
-
-=cut
-
-*/
-
-void *
-Parrot_memalign(size_t align, size_t size)
-{
- void *p;
- int i = posix_memalign(&p, align, size);
- return i == 0 ? p : NULL;
-}
-
-#elif defined(PARROT_HAS_MEMALIGN)
-
-# if defined(PARROT_HAS_HEADER_MALLOC)
-# include <malloc.h>
-# else
-# include <stdlib.h>
-# endif
-
-/*
-
-=item C<void * Parrot_memalign(size_t align, size_t size)>
-
-=cut
-
-*/
-
-void *
-Parrot_memalign(size_t align, size_t size)
-{
- return memalign(align, size);
-}
-
-#endif
-
-/*
-
-=item C<void Parrot_free_memalign(void *p)>
-
-=cut
-
-*/
-
-void
-Parrot_free_memalign(void *p)
-{
- free(p);
-}
-
-/*
-
-=back
-
-=cut
-
-*/
-
-/*
- * Local variables:
- * c-file-style: "parrot"
- * End:
- * vim: expandtab shiftwidth=4:
- */
Index: config/gen/platform/generic/time.c
===================================================================
--- config/gen/platform/generic/time.c (.../trunk) (revision 47551)
+++ config/gen/platform/generic/time.c (.../branches/cfunctionsdocs)
(revision 47869)
@@ -1,6 +1,6 @@
/*
* $Id$
- * Copyright (C) 2004-2006, Parrot Foundation.
+ * Copyright (C) 2004-2010, Parrot Foundation.
*/
/*
@@ -11,7 +11,7 @@
=head1 DESCRIPTION
-Time stuff
+Parrot time-related functions.
=head2 Functions
@@ -28,6 +28,8 @@
=item C<INTVAL Parrot_intval_time(void)>
+Parrot wrapper around standard library C<time()> function, returning an INTVAL.
+
=cut
*/
@@ -43,6 +45,8 @@
=item C<FLOATVAL Parrot_floatval_time(void)>
+Parrot wrapper around standard library function, returning a FLOATVAL.
+
=cut
*/
@@ -59,6 +63,8 @@
=item C<void Parrot_sleep(unsigned int seconds)>
+Parrot wrapper around standard library C<sleep()> function.
+
=cut
*/
@@ -90,6 +96,8 @@
=item C<struct tm * Parrot_gmtime_r(const time_t *t, struct tm *tm)>
+Parrot wrapper around standard library C<gmtime_r()> function.
+
=cut
*/
@@ -105,6 +113,8 @@
=item C<struct tm * Parrot_localtime_r(const time_t *t, struct tm *tm)>
+Parrot wrapper around standard library C<localtime_r()> function.
+
=cut
*/
@@ -120,6 +130,8 @@
=item C<char* Parrot_asctime_r(const struct tm *tm, char *buffer)>
+Parrot wrapper around standard library C<asctime_r()> function.
+
=cut
*/
Index: config/gen/platform/generic/dl.c
===================================================================
--- config/gen/platform/generic/dl.c (.../trunk) (revision 47551)
+++ config/gen/platform/generic/dl.c (.../branches/cfunctionsdocs)
(revision 47869)
@@ -1,6 +1,6 @@
/*
* $Id$
- * Copyright (C) 2004-2006, Parrot Foundation.
+ * Copyright (C) 2004-2010, Parrot Foundation.
*/
/*
@@ -11,7 +11,7 @@
=head1 DESCRIPTION
-Dynlib stuff
+Parrot functions which wrap around standard library functions for handling
dynamic libraries.
=head2 Functions
@@ -31,6 +31,9 @@
=item C<void * Parrot_dlopen(const char *filename, Parrot_dlopen_flags flags)>
+Wrapper around C<dlopen>. Loads dynamic library file named by first argument
+and returns a handle to it.
+
=cut
*/
@@ -50,6 +53,9 @@
=item C<const char * Parrot_dlerror(void)>
+Wrapper around C<dlerror>. System-dependent string that indicates most recent
+failure in use of C<Parrot_dlopen>, C<Parrot_dlclose> or C<Parrot_dlsym>.
+
=cut
*/
@@ -68,6 +74,9 @@
=item C<void * Parrot_dlsym(void *handle, const char *symbol)>
+Wrapper around C<dlysm>. Takes a handle returned by C<Parrot_dlopen> and
+returns address where symbol is located.
+
=cut
*/
@@ -86,6 +95,9 @@
=item C<int Parrot_dlclose(void *handle)>
+Wrapper around C<dl_close>. Releases reference to dynamic library specified
+by argument. Returns C<0> on success and C<-1> on failure.
+
=cut
*/
Index: config/gen/platform/generic/stat.c
===================================================================
--- config/gen/platform/generic/stat.c (.../trunk) (revision 47551)
+++ config/gen/platform/generic/stat.c (.../branches/cfunctionsdocs)
(revision 47869)
@@ -1,6 +1,6 @@
/*
* $Id$
- * Copyright (C) 2007-2008, Parrot Foundation.
+ * Copyright (C) 2007-2010, Parrot Foundation.
*/
/*
@@ -26,6 +26,8 @@
=item C<PMC * Parrot_stat_file(PARROT_INTERP, STRING *filename)>
+B<Not implemented.> Returns C<NULL>.
+
=cut
*/
@@ -41,6 +43,8 @@
=item C<PMC * Parrot_stat_info_pmc(PARROT_INTERP, STRING *filename, INTVAL
thing)>
+B<Not implemented.> Returns C<NULL>.
+
=cut
*/
@@ -56,6 +60,55 @@
=item C<static INTVAL stat_common(PARROT_INTERP, struct stat *statbuf, INTVAL
thing, int status)>
+Stats the file, and returns the information specified by C<thing>. C<thing> can
+be one of:
+
+=over 4
+
+=item * C<STAT_EXISTS>
+
+=item * C<STAT_FILESIZE>
+
+=item * C<STAT_ISDIR>
+
+=item * C<STAT_ISREG>
+
+=item * C<STAT_ISDEV>
+
+=item * C<STAT_ACCESSTIME>
+
+=item * C<STAT_MODIFYTIME>
+
+=item * C<STAT_CHANGETIME>
+
+=item * C<STAT_UID>
+
+=item * C<STAT_GID>
+
+=item * C<STAT_PLATFORM_DEV>
+
+=item * C<STAT_PLATFORM_INODE>
+
+=item * C<STAT_PLATFORM_MODE>
+
+=item * C<STAT_PLATFORM_NLINKS>
+
+=item * C<STAT_PLATFORM_DEVTYPE>
+
+=item * C<STAT_PLATFORM_MODE>
+
+=item * C<STAT_PLATFORM_NLINKS>
+
+=item * C<STAT_PLATFORM_DEVTYPE>
+
+=item * C<STAT_PLATFORM_BLOCKSIZE>
+
+=item * C<STAT_PLATFORM_BLOCKS>
+
+=back
+
+C<STAT_CREATETIME> and C<STAT_BACKUPTIME> are not supported and will return
C<-1>.
+
=cut
*/
@@ -141,6 +194,8 @@
=item C<INTVAL Parrot_stat_info_intval(PARROT_INTERP, STRING *file, INTVAL
thing)>
+Returns the stat field given by C<thing> of file C<file>.
+
=cut
*/
@@ -164,6 +219,8 @@
=item C<INTVAL Parrot_fstat_info_intval(PARROT_INTERP, INTVAL file, INTVAL
thing)>
+Returns the fstat field given by C<thing> from file identifier C<file>.
+
=cut
*/
@@ -184,6 +241,8 @@
=item C<FLOATVAL Parrot_stat_info_floatval(PARROT_INTERP, STRING *filename,
INTVAL thing)>
+Currently returns C<-1.0> and has no side effects.
+
=cut
*/
@@ -199,6 +258,8 @@
=item C<STRING * Parrot_stat_info_string(PARROT_INTERP, STRING *filename,
INTVAL
thing)>
+B<Not implemented.> Returns C<NULL>.
+
=cut
*/
Index: config/gen/platform/generic/exec.c
===================================================================
--- config/gen/platform/generic/exec.c (.../trunk) (revision 47551)
+++ config/gen/platform/generic/exec.c (.../branches/cfunctionsdocs)
(revision 47869)
@@ -1,6 +1,6 @@
/*
* $Id$
- * Copyright (C) 2004-2009, Parrot Foundation.
+ * Copyright (C) 2004-2010, Parrot Foundation.
*/
/*
@@ -11,7 +11,7 @@
=head1 DESCRIPTION
-system() stuff
+Parrot functions to run operating system commands.
=head2 Functions
@@ -28,8 +28,8 @@
=item C<INTVAL Parrot_Run_OS_Command(PARROT_INTERP, STRING *command)>
-Spawn off a subprocess and wait for the damn thing to complete,
-returning the return value of the process
+Spawn off a subprocess provided in a string. Wait for it to complete,
+returning the return value of the process.
=cut
@@ -72,6 +72,9 @@
=item C<INTVAL Parrot_Run_OS_Command_Argv(PARROT_INTERP, PMC *cmdargs)>
+Spawn off a subprocess provided in command-line arguments. Wait for it to
+complete, returning the return value of the process.
+
=cut
*/
@@ -125,6 +128,14 @@
}
/*
+
+=back
+
+=cut
+
+*/
+
+/*
* Local variables:
* c-file-style: "parrot"
* End:
Index: config/gen/platform/generic/math.c
===================================================================
--- config/gen/platform/generic/math.c (.../trunk) (revision 47551)
+++ config/gen/platform/generic/math.c (.../branches/cfunctionsdocs)
(revision 47869)
@@ -1,6 +1,6 @@
/*
* $Id$
- * Copyright (C) 2004-2007, Parrot Foundation.
+ * Copyright (C) 2004-2010, Parrot Foundation.
*/
/*
@@ -11,29 +11,21 @@
=head1 DESCRIPTION
-math stuff
+Mathematical functions.
=head2 Functions
=over 4
-=cut
-
-*/
-
-/*
-
=item C<extern int Parrot_signbit(double x)>
-return true if the Numval has a negative sign.
+Return true if the Numval has a negative sign.
This is mostly for handling the -0.0 case.
=cut
*/
-/*
- */
#if DOUBLE_SIZE == 2 * INT_SIZE
extern int
Parrot_signbit(double x)
@@ -55,6 +47,8 @@
=item C<int Parrot_signbit_l(long double x)>
+Like C<Parrot_signbit()>, only taking long double instead of double.
+
=cut
*/
Index: config/gen/platform/solaris/time.c
===================================================================
--- config/gen/platform/solaris/time.c (.../trunk) (revision 47551)
+++ config/gen/platform/solaris/time.c (.../branches/cfunctionsdocs)
(revision 47869)
@@ -1,6 +1,6 @@
/*
* $Id$
- * Copyright (C) 2004-2006, Parrot Foundation.
+ * Copyright (C) 2004-2010, Parrot Foundation.
*/
/*
@@ -11,7 +11,7 @@
=head1 DESCRIPTION
-Time stuff
+Parrot time-related functions.
=head2 Functions
@@ -28,6 +28,8 @@
=item C<INTVAL Parrot_intval_time(void)>
+Parrot wrapper around standard library C<time()> function, returning an INTVAL.
+
=cut
*/
@@ -43,6 +45,8 @@
=item C<FLOATVAL Parrot_floatval_time(void)>
+Parrot wrapper around standard library function, returning a FLOATVAL.
+
=cut
*/
@@ -59,6 +63,8 @@
=item C<void Parrot_sleep(unsigned int seconds)>
+Parrot wrapper around standard library C<sleep()> function.
+
=cut
*/
@@ -90,6 +96,8 @@
=item C<struct tm * Parrot_gmtime_r(const time_t *t, struct tm *tm)>
+Parrot wrapper around standard library C<gmtime_r()> function.
+
=cut
*/
@@ -105,6 +113,8 @@
=item C<struct tm * Parrot_localtime_r(const time_t *t, struct tm *tm)>
+Parrot wrapper around standard library C<localtime_r()> function.
+
=cut
*/
@@ -120,6 +130,8 @@
=item C<char* Parrot_asctime_r(const struct tm *tm, char *buffer)>
+Parrot wrapper around standard library C<asctime_r()> function.
+
=cut
*/
Index: config/gen/platform/solaris/math.c
===================================================================
--- config/gen/platform/solaris/math.c (.../trunk) (revision 47551)
+++ config/gen/platform/solaris/math.c (.../branches/cfunctionsdocs)
(revision 47869)
@@ -1,6 +1,6 @@
/*
* $Id$
- * Copyright (C) 2006-2007, Parrot Foundation.
+ * Copyright (C) 2006-2010, Parrot Foundation.
*/
/*
@@ -11,7 +11,7 @@
=head1 DESCRIPTION
-math stuff
+Mathematical functions.
=head2 Functions
@@ -35,7 +35,7 @@
=item C<extern int Parrot_signbit(double x)>
-return true if the Numval has a negative sign.
+Return true if the Numval has a negative sign.
This is mostly for handling the -0.0 case.
=cut
@@ -63,6 +63,8 @@
=item C<int Parrot_signbit_l(long double x)>
+Like C<Parrot_signbit()>, only taking long double instead of double.
+
=cut
*/
Index: examples/compilers/japhc.c
===================================================================
--- examples/compilers/japhc.c (.../trunk) (revision 47551)
+++ examples/compilers/japhc.c (.../branches/cfunctionsdocs) (revision 47869)
@@ -69,6 +69,8 @@
=item C<static int unescape(char *string)>
+Unescape a string.
+
=cut
*/
_______________________________________________
http://lists.parrot.org/mailman/listinfo/parrot-dev
