diff --git a/doc/command_funcref.txt b/doc/command_funcref.txt index dafab90..6208740 100644 --- a/doc/command_funcref.txt +++ b/doc/command_funcref.txt @@ -11,8 +11,8 @@ Description: on the subdevice indicated by the parameters device and subdevice. Returns: - If successful, 0 is returned, otherwise - -1. + On success, 0 is returned. + On failure, -1 is returned. Function: comedi_command -- start streaming input/output Retval: int @@ -33,8 +33,8 @@ Description: For output subdevices, sample values are written using the function write. Returns: - If successful, 0 is returned, otherwise - -1. + On success, 0 is returned. + On failure, -1 is returned. Function: comedi_command_test -- test streaming input/output configuration Retval: int @@ -48,7 +48,7 @@ Description: of the comedi_cmd structure are invalid, they may be modified. Source elements are modified to remove invalid source triggers. Argument elements are adjusted or rounded to the nearest valid value. - +Returns: The meanings of the return value are as follows: @@ -101,7 +101,8 @@ Description: use the same input range. - + + On failure, -1 is returned. Function: comedi_get_buffer_contents -- streaming buffer status Retval: int @@ -109,9 +110,14 @@ Param: comedi_t * device Param: unsigned int subdevice Description: The function comedi_get_buffer_contents is used on a subdevice - that has a Comedi command in progress. The number of bytes that - are available in the streaming buffer is returned. If there is - an error, -1 is returned. + that has a Comedi command in progress to get the number of unread bytes. For + a streaming input command, this is the number of bytes that can be read. For + a streaming output command, subtracting this from the buffer size gives the + space available to be written. +Returns: + On success, comedi_get_buffer_contents returns the + number of unread bytes in the buffer. + On failure, -1 is returned. Function: comedi_get_buffer_offset -- streaming buffer status Retval: int @@ -119,10 +125,14 @@ Param: comedi_t * device Param: unsigned int subdevice Description: The function comedi_get_buffer_offset is used on a subdevice - that has a Comedi command in progress. This function returns - the offset in bytes of the read pointer in the streaming buffer. + that has a Comedi command in progress to get the current read position in the + streaming buffer as an offset in bytes from the start of the buffer. + The position will wrap around to 0 when it reaches the buffer size. This offset is only useful for memory mapped buffers. - If there is an error, -1 is returned. +Returns: + On success, comedi_get_buffer_offset returns the current + read position as an offset in bytes from the start of the buffer. + On failure, -1 is returned. Function: comedi_get_buffer_size -- streaming buffer size of subdevice Retval: int @@ -133,7 +143,10 @@ Description: of the streaming buffer for the subdevice specified by device and subdevice. - On error, -1 is returned. +Returns: + On success, comedi_get_buffer_size returns the size of + the buffer in bytes. + On failure, -1 is returned. Function: comedi_get_cmd_generic_timed -- streaming input/output capabilities Retval: int @@ -162,8 +175,8 @@ Description: The rate is adjusted to a rate that the device can handle. Returns: - If successful, 0 is returned, otherwise - -1. + On success, 0 is returned. + On failure, -1 is returned. Function: comedi_get_cmd_src_mask -- streaming input/output capabilities Retval: int @@ -180,8 +193,8 @@ Description: of the subdevice's supported trigger sources. Other elements in the structure are undefined. Returns: - If successful, 0 is returned, otherwise - -1. + On success, 0 is returned. + On failure, -1 is returned. Function: comedi_get_max_buffer_size -- maximum streaming buffer size Retval: int @@ -197,7 +210,11 @@ Description: comedi_set_max_buffer_size or with the comedi_config program, - and requires appropriate privileges. On error, -1 is returned. + and requires appropriate privileges. +Returns: + On success, the maximum allowable size (in bytes) of the streaming buffer + is returned. + On failure, -1 is returned. Function: comedi_get_read_subdevice -- find streaming input subdevice Retval: int @@ -206,8 +223,12 @@ Description: The function comedi_get_read_subdevice returns the index of the subdevice whose streaming input buffer is currently accessible through the - device device. If - there is no such subdevice, -1 is returned. + device device, if there is one. +Returns: + On success, comedi_get_read_subdevicereturns the index + of the current read subdevice if there is one, + or -1 if there is no read subdevice. + On failure, -1 is returned. Function: comedi_get_write_subdevice -- find streaming output subdevice Retval: int @@ -216,8 +237,12 @@ Description: The function comedi_get_write_subdevice returns the index of the subdevice whose streaming output buffer is currently accessible through the - device device. If there is no such subdevice, - -1 is returned. + device device, if there is one. +Returns: + On success, comedi_get_write_subdevicereturns the index + of the current write subdevice if there is one, + or -1 if there is no write subdevice. + On failure, -1 is returned. Function: comedi_mark_buffer_read -- streaming buffer control Retval: int @@ -236,15 +261,10 @@ Description: bytes in the buffer are no longer needed and may be discarded. Returns: - The function comedi_mark_buffer_read returns the - number of bytes successfully marked as read, - or -1 on error. The return value may be less than - num_bytes if you attempt to mark more - bytes read than are currently available for reading, or - if num_bytes must be rounded down - to be an exact multiple of the subdevice's - sample size (either sizeof(sampl_t) or - sizeof(lsampl_t)). + On success, comedi_mark_buffer_read returns the + number of bytes successfully marked as read. The return value may be less than + the num_bytes. + On failure, -1 is returned. Function: comedi_mark_buffer_written -- streaming buffer control Retval: int @@ -263,16 +283,10 @@ Description: bytes in the buffer are valid and may be sent to the device. Returns: - The function comedi_mark_buffer_written returns - number of bytes successfully marked as written, - or -1 on error. The return value may be less than - num_bytes if you attempt to mark more - bytes written than the amount of free space currently available - in the output buffer, or - if num_bytes must be - rounded down to be an exact multiple of the subdevice's - sample size (either sizeof(sampl_t) - or sizeof(lsampl_t)). + On success, comedi_mark_buffer_written returns the + number of bytes successfully marked as written. The return value may be less than + the num_bytes. + On failure, -1 is returned. Function: comedi_poll -- force updating of streaming buffer Retval: int @@ -283,8 +297,12 @@ Description: Comedi command in progress in order to update the streaming buffer. If supported by the driver, all available samples are copied to the streaming buffer. These samples may be pending in DMA buffers - or device FIFOs. If successful, the number of additional bytes - available is returned. If there is an error, -1 is returned. + or device FIFOs. + Only a few Comedi drivers support this operation. +Returns: + On success, comedi_poll returns the number of additional + bytes available. + On failure, -1 is returned. Function: comedi_set_buffer_size -- streaming buffer size of subdevice Retval: int @@ -308,8 +326,9 @@ Description: linkend="func-ref-comedi-set-max-buffer-size">comedi_set_max_buffer_size, or running the program comedi_config. Returns: - The new buffer size in bytes is returned on success. On error, - -1 is returned. + On success, comedi_set_buffer_size returns the new + buffer size in bytes. + On failure, -1 is returned. Function: comedi_set_max_buffer_size -- streaming maximum buffer size of subdevice Retval: int @@ -323,7 +342,9 @@ Description: subdevice. Changing the maximum buffer size requires the user to have appropriate privileges. Returns: - The new maximum buffer size is returned on success. On error, -1 is returned. + On success, comedi_set_max_buffer_size returns the new + maximum buffer size in bytes. + On failure, -1 is returned. Function: comedi_set_read_subdevice -- set streaming input subdevice Retval: int @@ -339,7 +360,8 @@ Description: device and have no effect on other open file descriptions for the underlying device node. Returns: - 0 on success, -1 on error. + On success, 0 is returned. + On failure, -1 is returned. Function: comedi_set_write_subdevice -- set streaming output subdevice Retval: int @@ -355,4 +377,5 @@ Description: device and have no effect on other open file descriptions for the underlying device node. Returns: - 0 on success, -1 on error. + On success, 0 is returned. + On failure, -1 is returned.