Documentation update.
diff --git a/dlls/kernel/comm.c b/dlls/kernel/comm.c
index 8f4935b..34a28f0 100644
--- a/dlls/kernel/comm.c
+++ b/dlls/kernel/comm.c
@@ -1489,17 +1489,37 @@
/**************************************************************************
* BuildCommDCBA (KERNEL32.14)
+ *
+ * Updates a device control block data structure with values from an
+ * ascii device control string. The device control string has two forms
+ * normal and extended, it must be exclusively in one or the other form.
+ *
+ * RETURNS
+ *
+ * True on success, false on an malformed control string.
*/
-BOOL WINAPI BuildCommDCBA(LPCSTR device,LPDCB lpdcb)
+BOOL WINAPI BuildCommDCBA(
+ LPCSTR device, /* The ascii device control string used to update the DCB. */
+ LPDCB lpdcb /* The device control block to be updated. */)
{
return BuildCommDCBAndTimeoutsA(device,lpdcb,NULL);
}
/**************************************************************************
* BuildCommDCBAndTimeoutsA (KERNEL32.15)
+ *
+ * Updates a device control block data structure with values from an
+ * ascii device control string. Taking time out values from a time outs
+ * struct if desired by the control string.
+ *
+ * RETURNS
+ *
+ * True on success, false bad handles etc
*/
-BOOL WINAPI BuildCommDCBAndTimeoutsA(LPCSTR device, LPDCB lpdcb,
- LPCOMMTIMEOUTS lptimeouts)
+BOOL WINAPI BuildCommDCBAndTimeoutsA(
+ LPCSTR device, /* The ascii device control string. */
+ LPDCB lpdcb, /* The device control block to be updated. */
+ LPCOMMTIMEOUTS lptimeouts /* The time outs to use if asked to set them by the control string. */)
{
int port;
char *ptr,*temp;
@@ -1621,24 +1641,47 @@
/**************************************************************************
* BuildCommDCBAndTimeoutsW (KERNEL32.16)
+ *
+ * Updates a device control block data structure with values from an
+ * unicode device control string. Taking time out values from a time outs
+ * struct if desired by the control string.
+ *
+ * RETURNS
+ *
+ * True on success, false bad handles etc.
*/
-BOOL WINAPI BuildCommDCBAndTimeoutsW( LPCWSTR devid, LPDCB lpdcb,
- LPCOMMTIMEOUTS lptimeouts )
+BOOL WINAPI BuildCommDCBAndTimeoutsW(
+ LPCWSTR devid, /* The unicode device control string. */
+ LPDCB lpdcb, /* The device control block to be updated. */
+ LPCOMMTIMEOUTS lptimeouts /* The time outs to use if asked to set them by the control string. */)
{
+ BOOL ret = FALSE;
LPSTR devidA;
- BOOL ret;
TRACE("(%p,%p,%p)\n",devid,lpdcb,lptimeouts);
devidA = HEAP_strdupWtoA( GetProcessHeap(), 0, devid );
+ if (devidA)
+ {
ret=BuildCommDCBAndTimeoutsA(devidA,lpdcb,lptimeouts);
HeapFree( GetProcessHeap(), 0, devidA );
+ }
return ret;
}
/**************************************************************************
* BuildCommDCBW (KERNEL32.17)
+ *
+ * Updates a device control block structure with values from an
+ * unicode device control string. The device control string has two forms
+ * normal and extended, it must be exclusively in one or the other form.
+ *
+ * RETURNS
+ *
+ * True on success, false on an malformed control string.
*/
-BOOL WINAPI BuildCommDCBW(LPCWSTR devid,LPDCB lpdcb)
+BOOL WINAPI BuildCommDCBW(
+ LPCWSTR devid, /* The unicode device control string. */
+ LPDCB lpdcb /* The device control block to be updated. */)
{
return BuildCommDCBAndTimeoutsW(devid,lpdcb,NULL);
}
@@ -1648,8 +1691,20 @@
/*****************************************************************************
* SetCommBreak (KERNEL32.449)
+ *
+ * Halts the transmission of characters to a communications device.
+ *
+ * RETURNS
+ *
+ * True on success, and false if the communications device could not be found,
+ * the control is not supported.
+ *
+ * BUGS
+ *
+ * Only TIOCSBRK and TIOCCBRK are supported.
*/
-BOOL WINAPI SetCommBreak(HANDLE handle)
+BOOL WINAPI SetCommBreak(
+ HANDLE handle /* The communictions device to suspend. */)
{
#if defined(TIOCSBRK) && defined(TIOCCBRK) /* check if available for compilation */
int fd,result;
@@ -1677,8 +1732,19 @@
/*****************************************************************************
* ClearCommBreak (KERNEL32.20)
+ *
+ * Resumes character transmission from a communication device.
+ *
+ * RETURNS
+ *
+ * True on success and false if the communications device could not be found.
+ *
+ * BUGS
+ *
+ * Only TIOCSBRK and TIOCCBRK are supported.
*/
-BOOL WINAPI ClearCommBreak(HANDLE handle)
+BOOL WINAPI ClearCommBreak(
+ HANDLE handle /* The halted communication device whose character transmission is to be resumed. */)
{
#if defined(TIOCSBRK) && defined(TIOCCBRK) /* check if available for compilation */
int fd,result;
@@ -1706,8 +1772,18 @@
/*****************************************************************************
* EscapeCommFunction (KERNEL32.214)
+ *
+ * Directs a communication device to perform an extended function.
+ *
+ * RETURNS
+ *
+ * True or requested data on successful completion of the command,
+ * false if the device is not present cannot execute the command
+ * or the command failed.
*/
-BOOL WINAPI EscapeCommFunction(HANDLE handle,UINT nFunction)
+BOOL WINAPI EscapeCommFunction(
+ HANDLE handle, /* The communication device to perform the extended function. */
+ UINT nFunction /* The extended function to be performed. */)
{
int fd,direct=FALSE,result=FALSE;
struct termios port;
@@ -1814,8 +1890,17 @@
/********************************************************************
* PurgeComm (KERNEL32.557)
+ *
+ * Terminates pending operations and/or discards buffers on a
+ * communication resource.
+ *
+ * RETURNS
+ *
+ * True on success and false if the communications handle is bad.
*/
-BOOL WINAPI PurgeComm( HANDLE handle, DWORD flags)
+BOOL WINAPI PurgeComm(
+ HANDLE handle, /* The communication resource to be purged. */
+ DWORD flags /* Flags for clear pending/buffer on input/output. */)
{
int fd;
@@ -1847,8 +1932,18 @@
/*****************************************************************************
* ClearCommError (KERNEL32.21)
+ *
+ * Enables further I/O operations on a communications resource after
+ * supplying error and current status information.
+ *
+ * RETURNS
+ *
+ * True on success, false if the communication resource handle is bad.
*/
-BOOL WINAPI ClearCommError(HANDLE handle,LPDWORD errors,LPCOMSTAT lpStat)
+BOOL WINAPI ClearCommError(
+ HANDLE handle, /* The communication resource with the error. */
+ LPDWORD errors, /* Flags indicating error the resource experienced. */
+ LPCOMSTAT lpStat /* The status of the communication resource. */)
{
int fd;
@@ -1896,8 +1991,22 @@
/*****************************************************************************
* SetupComm (KERNEL32.676)
+ *
+ * Called after CreateFile to hint to the communication resource to use
+ * specified sizes for input and output buffers rather than the default values.
+ *
+ * RETURNS
+ *
+ * True if successful, false if the communications resource handle is bad.
+ *
+ * BUGS
+ *
+ * Stub.
*/
-BOOL WINAPI SetupComm( HANDLE handle, DWORD insize, DWORD outsize)
+BOOL WINAPI SetupComm(
+ HANDLE handle, /* The just created communication resource handle. */
+ DWORD insize, /* The suggested size of the communication resources input buffer in bytes. */
+ DWORD outsize /* The suggested size of the communication resources output buffer in bytes. */)
{
int fd;
@@ -1913,8 +2022,17 @@
/*****************************************************************************
* GetCommMask (KERNEL32.156)
+ *
+ * Obtain the events associated with a communication device that will cause a call
+ * WaitCommEvent to return.
+ *
+ * RETURNS
+ *
+ * True on success, fail on bad device handle etc.
*/
-BOOL WINAPI GetCommMask(HANDLE handle,LPDWORD evtmask)
+BOOL WINAPI GetCommMask(
+ HANDLE handle, /* The communications device. */
+ LPDWORD evtmask /* The events which cause WaitCommEvent to return. */)
{
BOOL ret;
@@ -1935,8 +2053,18 @@
/*****************************************************************************
* SetCommMask (KERNEL32.451)
+ *
+ * There be some things we need to hear about yon there communications device.
+ * (Set which events associated with a communication device should cause
+ * a call WaitCommEvent to return.)
+ *
+ * RETURNS
+ *
+ * True on success, false on bad handle etc.
*/
-BOOL WINAPI SetCommMask(HANDLE handle,DWORD evtmask)
+BOOL WINAPI SetCommMask(
+ HANDLE handle, /* The communications device. */
+ DWORD evtmask /* The events that to be monitored. */)
{
BOOL ret;
@@ -1956,12 +2084,21 @@
/*****************************************************************************
* SetCommState (KERNEL32.452)
+ *
+ * Re-initializes all hardware and control settings of a communications device,
+ * with values from a device control block without effecting the input and output
+ * queues.
+ *
+ * RETURNS
+ *
+ * True on success, false on failure eg if the XonChar is equal to the XoffChar.
*/
-BOOL WINAPI SetCommState(HANDLE handle,LPDCB lpdcb)
+BOOL WINAPI SetCommState(
+ HANDLE handle, /* The communications device. */
+ LPDCB lpdcb /* The device control block. */)
{
struct termios port;
- int fd;
- int bytesize, stopbits;
+ int fd, bytesize, stopbits;
TRACE("handle %d, ptr %p\n", handle, lpdcb);
TRACE("bytesize %d baudrate %ld fParity %d Parity %d stopbits %d\n",
@@ -2257,8 +2394,20 @@
/*****************************************************************************
* GetCommState (KERNEL32.159)
+ *
+ * Fills in a device control block with information from a communications device.
+ *
+ * RETURNS
+ *
+ * True on success, false if the communication device handle is bad etc
+ *
+ * BUGS
+ *
+ * XonChar and XoffChar are not set.
*/
-BOOL WINAPI GetCommState(HANDLE handle, LPDCB lpdcb)
+BOOL WINAPI GetCommState(
+ HANDLE handle, /* The communications device. */
+ LPDCB lpdcb /* The device control block. */)
{
struct termios port;
int fd,speed;
@@ -2449,8 +2598,22 @@
/*****************************************************************************
* TransmitCommChar (KERNEL32.535)
+ *
+ * Transmits a single character in front of any pending characters in the
+ * output buffer. Usually used to send an interrupt character to a host.
+ *
+ * RETURNS
+ *
+ * True if the call succeeded, false if the previous command character to the
+ * same device has not been sent yet the handle is bad etc.
+ *
+ * BUGS
+ *
+ * Stub.
*/
-BOOL WINAPI TransmitCommChar(HANDLE hComm,CHAR chTransmit)
+BOOL WINAPI TransmitCommChar(
+ HANDLE hComm, /* The communication device in need of a command character. */
+ CHAR chTransmit /* The character to transmit. */)
{
FIXME("(%x,'%c'), use win32 handle!\n",hComm,chTransmit);
return TRUE;
@@ -2458,8 +2621,17 @@
/*****************************************************************************
* GetCommTimeouts (KERNEL32.160)
+ *
+ * Obtains the request time out values for the communications device.
+ *
+ * RETURNS
+ *
+ * True on success, false if communications device handle is bad
+ * or the target structure is null.
*/
-BOOL WINAPI GetCommTimeouts(HANDLE hComm,LPCOMMTIMEOUTS lptimeouts)
+BOOL WINAPI GetCommTimeouts(
+ HANDLE hComm, /* The communications device. */
+ LPCOMMTIMEOUTS lptimeouts /* The struct of request time outs. */)
{
BOOL ret;
@@ -2499,6 +2671,10 @@
* - used in ReadFile to calculate GetOverlappedResult's timeout
* WriteTotalTimeoutMultiplier, WriteTotalTimeoutConstant
* - used in WriteFile to calculate GetOverlappedResult's timeout
+ *
+ * RETURNS
+ *
+ * True if the time outs were set, false otherwise.
*/
BOOL WINAPI SetCommTimeouts(
HANDLE hComm, /* [in] handle of COMM device */
@@ -2554,8 +2730,17 @@
/***********************************************************************
* GetCommModemStatus (KERNEL32.285)
+ *
+ * Obtains the four control register bits if supported by the hardware.
+ *
+ * RETURNS
+ *
+ * True if the communications handle was good and for hardware that
+ * control register access, false otherwise.
*/
-BOOL WINAPI GetCommModemStatus(HANDLE hFile,LPDWORD lpModemStat )
+BOOL WINAPI GetCommModemStatus(
+ HANDLE hFile, /* The communications device. */
+ LPDWORD lpModemStat /* The control register bits. */)
{
int fd,mstat, result=FALSE;
@@ -2844,10 +3029,18 @@
*
* TRUE on success, FALSE on failure
* If successful, lpCommConfig contains the comm port configuration.
+ *
+ * BUGS
+ *
+ * The signature is missing a the parameter for the size of the COMMCONFIG
+ * structure/buffer it should be
+ * BOOL WINAPI GetCommConfig(HANDLE hFile,LPCOMMCONFIG lpCommConfig,LPDWORD lpdwSize)
*/
BOOL WINAPI GetCommConfig(
- HANDLE hFile,
- LPCOMMCONFIG lpCommConfig
+ HANDLE hFile, /* The communications device. */
+ LPCOMMCONFIG lpCommConfig /* The communications configuration of the device (if it fits). */
+ /* LPDWORD lpdwSize Initially the size of the configuration buffer/structure,
+ afterwards the number of bytes copied to the buffer or the needed size of the buffer. */
) {
BOOL r;
@@ -2870,26 +3063,34 @@
/***********************************************************************
* SetCommConfig (KERNEL32.617)
*
+ * Sets the configuration of the commications device.
+ *
+ * RETURNS
+ *
+ * True on success, false if the handle was bad is not a communications device.
*/
BOOL WINAPI SetCommConfig(
- HANDLE hFile,
- LPCOMMCONFIG lpCommConfig
+ HANDLE hFile, /* The communications device. */
+ LPCOMMCONFIG lpCommConfig /* The desired configuration. */
) {
- BOOL r;
-
TRACE("(%x %p)\n",hFile,lpCommConfig);
-
- r = SetCommState(hFile,&lpCommConfig->dcb);
- return r;
+ return SetCommState(hFile,&lpCommConfig->dcb);
}
/***********************************************************************
* SetDefaultCommConfigA (KERNEL32.638)
+ *
+ * Initializes the default configuration for the specified communication
+ * device. (ascii)
+ *
+ * RETURNS
+ *
+ * True if the device was found and the defaults set, false otherwise
*/
BOOL WINAPI SetDefaultCommConfigA(
- LPCSTR lpszDevice,
- LPCOMMCONFIG lpCommConfig,
- DWORD dwSize
+ LPCSTR lpszDevice, /* The ascii name of the device targeted for configuration. */
+ LPCOMMCONFIG lpCommConfig, /* The default configuration for the device. */
+ DWORD dwSize /* The number of bytes in the configuration structure. */
) {
FARPROC lpfnSetDefaultCommConfig;
HMODULE hConfigModule;
@@ -2917,11 +3118,16 @@
/***********************************************************************
* SetDefaultCommConfigW (KERNEL32.639)
*
+ * Initializes the default configuration for the specified
+ * communication device. (unicode)
+ *
+ * RETURNS
+ *
*/
BOOL WINAPI SetDefaultCommConfigW(
- LPCWSTR lpszDevice,
- LPCOMMCONFIG lpCommConfig,
- DWORD dwSize
+ LPCWSTR lpszDevice, /* The unicode name of the device targeted for configuration. */
+ LPCOMMCONFIG lpCommConfig, /* The default configuration for the device. */
+ DWORD dwSize /* The number of bytes in the configuration structure. */
) {
BOOL r;
LPSTR lpDeviceA;
@@ -2939,10 +3145,20 @@
/***********************************************************************
* GetDefaultCommConfigA (KERNEL32.313)
+ *
+ * Acquires the default configuration of the specified communication device. (unicode)
+ *
+ * RETURNS
+ *
+ * True on successful reading of the default configuration,
+ * if the device is not found or the buffer is too small.
*/
-BOOL WINAPI GetDefaultCommConfigA(LPCSTR lpszName,LPCOMMCONFIG lpCC,
- LPDWORD lpdwSize)
-{
+BOOL WINAPI GetDefaultCommConfigA(
+ LPCSTR lpszName, /* The ascii name of the device targeted for configuration. */
+ LPCOMMCONFIG lpCC, /* The default configuration for the device. */
+ LPDWORD lpdwSize ) /* Initially the size of the default configuration buffer,
+ afterwards the number of bytes copied to the buffer or the needed size of the buffer. */
+{
LPDCB lpdcb = &(lpCC->dcb);
char temp[40];
@@ -2976,17 +3192,30 @@
/**************************************************************************
* GetDefaultCommConfigW (KERNEL32.314)
+ *
+ * Acquires the default configuration of the specified communication device. (unicode)
+ *
+ * RETURNS
+ *
+ * True on successful reading of the default configuration,
+ * if the device is not found or the buffer is too small.
*/
-BOOL WINAPI GetDefaultCommConfigW( LPCWSTR lpszName,LPCOMMCONFIG lpCC,
- LPDWORD lpdwSize)
-{
+BOOL WINAPI GetDefaultCommConfigW(
+ LPCWSTR lpszName, /* The unicode name of the device targeted for configuration. */
+ LPCOMMCONFIG lpCC, /* The default configuration for the device. */
+ LPDWORD lpdwSize /* Initially the size of the default configuration buffer,
+ afterwards the number of bytes copied to the buffer or the needed size of the buffer. */
+) {
+ BOOL ret = FALSE;
LPSTR lpszNameA;
- BOOL ret;
TRACE("(%p,%p,%ld)\n",lpszName,lpCC,*lpdwSize);
lpszNameA = HEAP_strdupWtoA( GetProcessHeap(), 0, lpszName );
+ if (lpszNameA)
+ {
ret=GetDefaultCommConfigA(lpszNameA,lpCC,lpdwSize);
HeapFree( GetProcessHeap(), 0, lpszNameA );
+ }
return ret;
}
diff --git a/dlls/kernel/debugger.c b/dlls/kernel/debugger.c
index 39b7fc9..77c4d22 100644
--- a/dlls/kernel/debugger.c
+++ b/dlls/kernel/debugger.c
@@ -19,15 +19,16 @@
/******************************************************************************
* WaitForDebugEvent (KERNEL32.720)
*
- * Waits for a debugging event to occur in a process being debugged
+ * Waits for a debugging event to occur in a process being debugged before
+ * filling out the debug event structure.
*
- * PARAMS
- * event [I] Address of structure for event information
- * timeout [I] Number of milliseconds to wait for event
+ * RETURNS
*
- * RETURNS STD
+ * Returns true if a debug event occurred and false if the call timed out.
*/
-BOOL WINAPI WaitForDebugEvent( LPDEBUG_EVENT event, DWORD timeout )
+BOOL WINAPI WaitForDebugEvent(
+ LPDEBUG_EVENT event, /* Address of structure for event information. */
+ DWORD timeout /* Number of milliseconds to wait for event. */)
{
BOOL ret;
SERVER_START_REQ
@@ -111,8 +112,18 @@
/**********************************************************************
* ContinueDebugEvent (KERNEL32.146)
+ *
+ * Enables a thread that previously produced a debug event to continue.
+ *
+ * RETURNS
+ *
+ * True if the debugger is listed as the processes owner and the process
+ * and thread are valid.
*/
-BOOL WINAPI ContinueDebugEvent( DWORD pid, DWORD tid, DWORD status )
+BOOL WINAPI ContinueDebugEvent(
+ DWORD pid, /* The id of the process to continue. */
+ DWORD tid, /* The id of the thread to continue. */
+ DWORD status /* The rule to apply to unhandled exeptions. */)
{
BOOL ret;
SERVER_START_REQ
@@ -130,8 +141,15 @@
/**********************************************************************
* DebugActiveProcess (KERNEL32.180)
+ *
+ * Attempts to attach the dugger to a process.
+ *
+ * RETURNS
+ *
+ * True if the debugger was attached to process.
*/
-BOOL WINAPI DebugActiveProcess( DWORD pid )
+BOOL WINAPI DebugActiveProcess(
+ DWORD pid /* The process to be debugged. */)
{
BOOL ret;
SERVER_START_REQ
@@ -147,8 +165,12 @@
/***********************************************************************
* OutputDebugStringA (KERNEL32.548)
+ *
+ * Output by an application of a unicode string to a debugger (if attached)
+ * and program log.
*/
-void WINAPI OutputDebugStringA( LPCSTR str )
+void WINAPI OutputDebugStringA(
+ LPCSTR str /* The message to be logged and given to the debugger. */)
{
SERVER_START_REQ
{
@@ -165,8 +187,12 @@
/***********************************************************************
* OutputDebugStringW (KERNEL32.549)
+ *
+ * Output by an appliccation of a unicode string to a debugger (if attached)
+ * and program log.
*/
-void WINAPI OutputDebugStringW( LPCWSTR str )
+void WINAPI OutputDebugStringW(
+ LPCWSTR str /* The message to be logged and given to the debugger. */)
{
SERVER_START_REQ
{
@@ -183,8 +209,12 @@
/***********************************************************************
* OutputDebugString16 (KERNEL.115)
+ *
+ * Output by a 16 bit application of an ascii string to a debugger (if attached)
+ * and program log.
*/
-void WINAPI OutputDebugString16( LPCSTR str )
+void WINAPI OutputDebugString16(
+ LPCSTR str /* The message to be logged and given to the debugger.*/)
{
OutputDebugStringA( str );
}
@@ -192,6 +222,9 @@
/***********************************************************************
* DebugBreak (KERNEL32.181)
+ *
+ * Raises an exception so that a debugger (if attached)
+ * can take some action.
*/
void WINAPI DebugBreak(void)
{
@@ -201,8 +234,16 @@
/***********************************************************************
* DebugBreak16 (KERNEL.203)
+ *
+ * Raises an expection in a 16 bit application so that a debugger (if attached)
+ * can take some action.
+ *
+ * BUGS
+ *
+ * Only 386 compatible processors implemented.
*/
-void WINAPI DebugBreak16( CONTEXT86 *context )
+void WINAPI DebugBreak16(
+ CONTEXT86 *context /* A pointer to the 386 compatible processor state. */)
{
#ifdef __i386__
EXCEPTION_RECORD rec;
@@ -219,6 +260,12 @@
/***********************************************************************
* IsDebuggerPresent (KERNEL32)
+ *
+ * Allows a process to determine if there is a debugger attached.
+ *
+ * RETURNS
+ *
+ * True if there is a debugger attached.
*/
BOOL WINAPI IsDebuggerPresent(void)
{
diff --git a/dlls/kernel/time.c b/dlls/kernel/time.c
index 8bfdd21..933e74b 100644
--- a/dlls/kernel/time.c
+++ b/dlls/kernel/time.c
@@ -33,10 +33,15 @@
/***********************************************************************
* SetLocalTime (KERNEL32.655)
*
- * FIXME: correct ? Is the timezone param of settimeofday() needed ?
- * I don't have any docu about SetLocal/SystemTime(), argl...
+ * Sets the local time using current time zone and daylight
+ * savings settings.
+ *
+ * RETURNS
+ *
+ * True if the time was set, false if the time was invalid or the
+ * necessary permissions were not held.
*/
-BOOL WINAPI SetLocalTime(const SYSTEMTIME *systime)
+BOOL WINAPI SetLocalTime( const SYSTEMTIME *systime /* The desired local time. */ )
{
struct timeval tv;
struct tm t;
@@ -80,10 +85,22 @@
/***********************************************************************
* GetSystemTimeAdjustment (KERNEL32.407)
*
+ * Indicates the period between clock interrupt and the amount the clock
+ * is adjusted each interrupt so as to keep it insync with an external source.
+ *
+ * RETURNS
+ *
+ * Always returns true.
+ *
+ * BUGS
+ *
+ * Only the special case of disabled time adjustments is supported.
+ * (also the signature is wrong it should have a return type of BOOL)
*/
-DWORD WINAPI GetSystemTimeAdjustment( LPDWORD lpTimeAdjustment,
- LPDWORD lpTimeIncrement,
- LPBOOL lpTimeAdjustmentDisabled )
+DWORD WINAPI GetSystemTimeAdjustment(
+ LPDWORD lpTimeAdjustment, /* The clock adjustment per interupt in 100's of nanoseconds. */
+ LPDWORD lpTimeIncrement, /* The time between clock interupts in 100's of nanoseconds. */
+ LPBOOL lpTimeAdjustmentDisabled /* The clock synchonisation has been disabled. */ )
{
*lpTimeAdjustment = 0;
*lpTimeIncrement = 0;
@@ -94,8 +111,16 @@
/***********************************************************************
* SetSystemTime (KERNEL32.507)
+ *
+ * Sets the system time (utc).
+ *
+ * RETURNS
+ *
+ * True if the time was set, false if the time was invalid or the
+ * necessary permissions were not held.
*/
-BOOL WINAPI SetSystemTime(const SYSTEMTIME *systime)
+BOOL WINAPI SetSystemTime(
+ const SYSTEMTIME *systime /* The desired system time. */)
{
struct timeval tv;
struct timezone tz;
@@ -147,8 +172,16 @@
/***********************************************************************
* GetTimeZoneInformation (KERNEL32.302)
+ *
+ * Fills in the a time zone information structure with values based on
+ * the current local time.
+ *
+ * RETURNS
+ *
+ * The daylight savings time standard or TIME_ZONE_ID_INVALID if the call failed.
*/
-DWORD WINAPI GetTimeZoneInformation(LPTIME_ZONE_INFORMATION tzinfo)
+DWORD WINAPI GetTimeZoneInformation(
+ LPTIME_ZONE_INFORMATION tzinfo /* The time zone structure to be filled in. */)
{
time_t gmt;
int bias, daylight;
@@ -168,8 +201,19 @@
/***********************************************************************
* SetTimeZoneInformation (KERNEL32.515)
+ *
+ * Set the local time zone with values based on the time zone structure.
+ *
+ * RETURNS
+ *
+ * True on successful setting of the time zone.
+ *
+ * BUGS
+ *
+ * Use the obsolete unix timezone structure and tz_dsttime member.
*/
-BOOL WINAPI SetTimeZoneInformation(const LPTIME_ZONE_INFORMATION tzinfo)
+BOOL WINAPI SetTimeZoneInformation(
+ const LPTIME_ZONE_INFORMATION tzinfo /* The new time zone. */)
{
struct timezone tz;
@@ -185,11 +229,21 @@
/***********************************************************************
* SystemTimeToTzSpecificLocalTime (KERNEL32.683)
+ *
+ * Converts the system time (utc) to the local time in the specified time zone.
+ *
+ * RETURNS
+ *
+ * Returns true when the local time was calculated.
+ *
+ * BUGS
+ *
+ * Does not handle daylight savings time adjustments correctly.
*/
BOOL WINAPI SystemTimeToTzSpecificLocalTime(
- LPTIME_ZONE_INFORMATION lpTimeZoneInformation,
- LPSYSTEMTIME lpUniversalTime,
- LPSYSTEMTIME lpLocalTime)
+ LPTIME_ZONE_INFORMATION lpTimeZoneInformation, /* The desired time zone. */
+ LPSYSTEMTIME lpUniversalTime, /* The utc time to base local time on. */
+ LPSYSTEMTIME lpLocalTime /* The local time in the time zone. */)
{
FIXME(":stub\n");
SetLastError(ERROR_CALL_NOT_IMPLEMENTED);
@@ -199,18 +253,21 @@
/***********************************************************************
* GetSystemTimeAsFileTime (KERNEL32)
+ *
+ * Fills in a file time structure with the current time in UTC format.
*/
-VOID WINAPI GetSystemTimeAsFileTime( LPFILETIME time )
+VOID WINAPI GetSystemTimeAsFileTime(
+ LPFILETIME time /* The file time struct to be filled with the system time. */)
{
NtQuerySystemTime( (LARGE_INTEGER *)time );
}
/*********************************************************************
- * TIME_ClockTimeToFileTime
- * (olorin@fandra.org, 20-Sep-1998)
- * Converts clock_t into FILETIME.
- * Used by GetProcessTime.
+ * TIME_ClockTimeToFileTime (olorin@fandra.org, 20-Sep-1998)
+ *
+ * Used by GetProcessTimes to convert clock_t into FILETIME.
+ *
* Differences to UnixTimeToFileTime:
* 1) Divided by CLK_TCK
* 2) Time is relative. There is no 'starting date', so there is
@@ -225,14 +282,27 @@
/*********************************************************************
* GetProcessTimes [KERNEL32.262]
*
- * FIXME: lpCreationTime, lpExitTime are NOT INITIALIZED.
- * olorin@fandra.org: Would be nice to substract the cpu time,
- * used by Wine at startup.
- * Also, there is a need to separate times
- * used by different applications.
+ * Returns the user and kernel execution times of a process,
+ * along with the creation and exit times if known.
+ *
+ * olorin@fandra.org:
+ * Would be nice to subtract the cpu time, used by Wine at startup.
+ * Also, there is a need to separate times used by different applications.
+ *
+ * RETURNS
+ *
+ * Always returns true.
+ *
+ * BUGS
+ *
+ * lpCreationTime, lpExitTime are NOT INITIALIZED.
*/
-BOOL WINAPI GetProcessTimes( HANDLE hprocess,LPFILETIME lpCreationTime,LPFILETIME lpExitTime,
- LPFILETIME lpKernelTime, LPFILETIME lpUserTime )
+BOOL WINAPI GetProcessTimes(
+ HANDLE hprocess, /* The process to be queried (obtained from PROCESS_QUERY_INFORMATION). */
+ LPFILETIME lpCreationTime, /* The creation time of the process. */
+ LPFILETIME lpExitTime, /* The exit time of the process if exited. */
+ LPFILETIME lpKernelTime, /* The time spent in kernal routines in 100's of nanoseconds. */
+ LPFILETIME lpUserTime /* The time spent in user routines in 100's of nanoseconds. */)
{
struct tms tms;
