OWCAPI(1) One-Wire File System OWCAPI(1)

# [NAME](#NAME)

**owcapi** - easy C-language 1-wire interface

# [SYNOPSIS](#SYNOPSIS)

**libowcapi** library to link with your program

## [Initialization](#Initialization)

**ssize\_t OW\_init(** *device name or full parameter string* **)**  
**ssize\_t OW\_init\_args(** *int argc, char \** args* **)**

The full set of initialization options is extensive. They correspond roughly to the command line options of [**owfs (1)**](/man/os/owfs/owfs.1) **owhttpd (1)** and [**owftpd (1)**](/man/os/owfs/owftpd.1)

## [Get data](#Get_data)

**int OW\_present(** *const char * path* **)**  
**int OW\_get(** *const char * path, char \** buffer, size\_t * buffer\_length* **)**  
**ssize\_t OW\_lread(** *const char * path, unsigned char * buffer, const size\_t size, const off\_t offset* **)**

## [Set data](#Set_data)

**ssize\_t OW\_put(** *const char * path, const char * buffer, size\_t * buffer\_length* **)**  
**ssize\_t OW\_lwrite(** *const char * path, const unsigned char * buffer, const size\_t size, const off\_t offset* **)**

## [Debug](#Debug)

**void OW\_set\_error\_level(** *const char \*param* **)**  
**void OW\_set\_error\_print(** *const char \*param* **)**

## [Close](#Close)

**void OW\_finish(** *void* **)**

# [FUNCTIONS](#FUNCTIONS)

## [OW\_init](#OW_init)

*OW\_init\_string* offers the full flexibility of the **owfs (1)** and [**owhttpd (1)**](/man/os/owfs/owhttpd.1) command line.

[*Arguments*](#Arguments)

Can be as simple as jus the device name, a full parameter specification. One or more device names (includes tcp, serial, usb...) and command line switches. See [**owfs (1)**](/man/os/owfs/owfs.1) for full syntax.

[*Returns*](#Returns)

0 for success. -1 on error and *errno* will be set. *OW\_finish* does not need to be called if *OW\_init* fails.

[*Sequence*](#Sequence)

One of the *init* functions must be called before accessing the 1-wire bus. *OW\_finish* is optional.

## [OW\_init\_args](#OW_init_args)

*OW\_init\_args* offers the full flexibility of the **owfs (1)** and [**owhttpd (1)**](/man/os/owfs/owhttpd.1) command line.

[*Arguments*](#Arguments~2)

One or more device names (includes tcp, serial, usb...) and command line switches. See [**owfs (1)**](/man/os/owfs/owfs.1) for full syntax. Unlike *OW\_init\_string* the arguments are in argv/argc format.

[*Returns*](#Returns~2)

0 for success. -1 on error and *errno* will be set. *OW\_finish* does not need to be called if *OW\_init* fails.

[*Sequence*](#Sequence~2)

One of the *init* functions must be called before accessing the 1-wire bus. *OW\_finish* is optional.

## [OW\_present](#OW_present)

*OW\_present* is used to check presence of a 1-wire device.

[*Arguments*](#Arguments~3)

*path* is the path to the directory or file (property).

[*Returns*](#Returns~3)

0 on success. -1 on error (and *errno* is set).

[*Sequence*](#Sequence~3)

One of the *init* functions must be called before accessing the 1-wire bus. *OW\_finish* is optional.

## [OW\_get](#OW_get)

*OW\_get* is used to get directory listings and file contents. The results are put in a dynamically allocated buffer.

[*Arguments*](#Arguments~4)

*path* is the path to the directory or file (property). *\*buffer* returns a pointer to a buffer containing the directory (comma separated) or value. *buffer\_length* returns the length of the value/string in *buffer*

[*Returns*](#Returns~4)

number of bytes on success. -1 on error (and *errno* is set).

[*Sequence*](#Sequence~4)

One of the *init* functions must be called before accessing the 1-wire bus. *OW\_finish* is optional.

[*Important note*](#Important)

*buffer* is allocated ( with malloc ) by *OW\_get* but must be freed in your program. See [**malloc (3)**](/man/os/owfs/malloc.3) and [**free (3)**](/man/os/owfs/free.3)

## [OW\_lread](#OW_lread)

*OW\_lread* is used to read 1-wire memory chips. Think of it as a combination of *lseek* and *read* It allows random-access to the memory, specifying location and length. Unlike *OW\_get* directories cannot be obtained and the buffer must be pre-allocated rather than allocated by the routine. *buffer* must be at least *size* length.

[*Arguments*](#Arguments~5)

*path* is the path to the file (property). *buffer* is the (pre-allocated) memory area where the value will be placed. *size* is the length of bytes requested. *offset* is the position in file to start reading.

[*Returns*](#Returns~5)

number of bytes on success. -1 on error (and *errno* is set).

[*Sequence*](#Sequence~5)

One of the *init* functions must be called before accessing the 1-wire bus. *OW\_finish* is optional.

## [OW\_put](#OW_put)

*OW\_put* is an easy way to write to 1-wire chips.

[*Arguments*](#Arguments~6)

*path* is the path to the file (property). *buffer* is the value to be written. *buffer\_length* is the length of the value *buffer.* *Returns* number of bytes on success. -1 on error (and *errno* is set).

[*Sequence*](#Sequence~6)

One of the *init* functions must be called before accessing the 1-wire bus. *OW\_finish* is optional.

## [OW\_lwrite](#OW_lwrite)

*OW\_lwrite* is the companion of *OW\_lread.* It allows writing to arbitrary positions in 1-wire memory. Think of it as a combination of *lseek* and *write.* *buffer* must be at least *size* length.

[*Arguments*](#Arguments~7)

*path* is the path to the file (property). *buffer* is the data to be written. *size* is the length of bytes to be written. *offset* is the position in file to start writing.

[*Returns*](#Returns~6)

number of bytes on success. -1 on error (and *errno* is set).

[*Sequence*](#Sequence~7)

One of the *init* functions must be called before accessing the 1-wire bus. *OW\_finish* is optional.

## [OW\_set\_error\_level](#OW_set_error_level)

*OW\_set\_error\_level* sets the debug output to a certain level. 0 is default, and higher value gives more output.  
(0=default, 1=err\_connect, 2=err\_call, 3=err\_data, 4=err\_detail, 5=err\_debug, 6=err\_beyond)

[*Arguments*](#Arguments~8)

*params* is the level. Should be an integer.

[*Returns*](#Returns~7)

None

[*Sequence*](#Sequence~8)

One of the *init* functions must be called before setting the level, since *init* defaults to level 0.

## [OW\_set\_error\_print](#OW_set_error_print)

*OW\_set\_error\_print* sets where the debug output should be directed. 0=mixed output, 1=syslog, 2=console.

[*Arguments*](#Arguments~9)

*params* is the level. Should be an integer between 0 and 2.

[*Returns*](#Returns~8)

None

[*Sequence*](#Sequence~9)

One of the *init* functions must be called before setting the level, since *init* defaults to 0 (mixed output).

## [OW\_finish](#OW_finish)

*OW\_finish* cleans up the *OWFS* 1-wire routines, releases devices and memory.

[*Arguments*](#Arguments~10)

None.

[*Returns*](#Returns~9)

None

[*Sequence*](#Sequence~10)

*OW\_finish* is optional since cleanup is automatic on program exit.

# [DESCRIPTION](#DESCRIPTION)

See the file man1/description.1so.

## [libowcapi](#libowcapi)

[**libowcapi (1)**](/man/os/owfs/libowcapi.1) is an encapsulation of the full **libow** library for C programs.

[**libowcapi (1)**](/man/os/owfs/libowcapi.1) allows a C program to use *OWFS* principles (consistent naming scheme, multiple adapters, devices, and compatibility) directly from a C program. There are analogous modules for other programming languages:

[*C*](#C)

libowcapi

[*perl*](#perl)

owperl

[*php*](#php)

owphp

[*python*](#python)

owpython

[*tcl*](#tcl)

owtcl

# [EXAMPLE](#EXAMPLE)

/* Simple directory listing -- no error checking \*/  
#include <owcapi.h>  
unsigned char * buf;  
size\_t s ;  
OW\_init("/dev/ttyS0");  
OW\_set\_error\_print("2");  
OW\_set\_error\_level("6");  
OW\_get("/",&buf,&s) ;  
printf("Directory %s0,buf);  
free(buf);  
OW\_finish() ;

# [SEE ALSO](#SEE_ALSO)

See the file man1/seealso.1so.

# [AVAILABILITY](#AVAILABILITY)

http://www.owfs.org

# [AUTHOR](#AUTHOR)

Paul Alfille (paul.alfille@gmail.com)

2004 OWFS Manpage

---

Document: owcapi(1) from owfs 3.2.4-r8 (Chainguard OS)
Source: https://github.com/owfs/owfs