xref: /freebsd/contrib/libfido2/man/fido_dev_set_io_functions.3 (revision 1b10e191f341111fad7be32ead11484dfd09b800)
1.\" Copyright (c) 2018 Yubico AB. All rights reserved.
2.\" Use of this source code is governed by a BSD-style
3.\" license that can be found in the LICENSE file.
4.\"
5.Dd $Mdocdate: May 25 2018 $
6.Dt FIDO_DEV_SET_IO_FUNCTIONS 3
7.Os
8.Sh NAME
9.Nm fido_dev_set_io_functions ,
10.Nm fido_dev_set_sigmask
11.Nd FIDO 2 device I/O interface
12.Sh SYNOPSIS
13.In fido.h
14.Bd -literal
15typedef void *fido_dev_io_open_t(const char *);
16typedef void  fido_dev_io_close_t(void *);
17typedef int   fido_dev_io_read_t(void *, unsigned char *, size_t, int);
18typedef int   fido_dev_io_write_t(void *, const unsigned char *, size_t);
19
20typedef struct fido_dev_io {
21	fido_dev_io_open_t  *open;
22	fido_dev_io_close_t *close;
23	fido_dev_io_read_t  *read;
24	fido_dev_io_write_t *write;
25} fido_dev_io_t;
26
27#ifdef _WIN32
28typedef int fido_sigset_t;
29#else
30typedef sigset_t fido_sigset_t;
31#endif
32.Ed
33.Ft int
34.Fn fido_dev_set_io_functions "fido_dev_t *dev" "const fido_dev_io_t *io"
35.Ft int
36.Fn fido_dev_set_sigmask "fido_dev_t *dev" "const fido_sigset_t *sigmask"
37.Sh DESCRIPTION
38The
39.Fn fido_dev_set_io_functions
40function sets the I/O handlers used by
41.Em libfido2
42to talk to
43.Fa dev .
44By default, these handlers are set to the operating system's native HID or NFC
45interfaces.
46They are defined as follows:
47.Bl -tag -width Ds
48.It Vt fido_dev_open_t
49Receives a
50.Vt const char *
51holding a path and opens the corresponding device, returning a
52non-NULL opaque pointer on success and NULL on error.
53.It Vt fido_dev_close_t
54Receives the opaque pointer returned by
55.Vt fido_dev_open_t
56and closes the device.
57.It Vt fido_dev_read_t
58Reads a single transmission unit (HID report, APDU) from a device.
59The first parameter is the opaque pointer returned by
60.Vt fido_dev_open_t .
61The second parameter is the read buffer, and the third parameter
62is the read buffer size.
63The fourth parameter is the number of milliseconds the caller is
64willing to sleep, should the call need to block.
65If this value holds -1,
66.Vt fido_dev_read_t
67may block indefinitely.
68On success, the number of bytes read is returned.
69On error, -1 is returned.
70.It Vt fido_dev_write_t
71Writes a single transmission unit (HID report, APDU) to
72.Fa dev .
73The first parameter is the opaque pointer returned by
74.Vt fido_dev_open_t .
75The second parameter is the write buffer, and the third parameter
76is the number of bytes to be written.
77A
78.Vt fido_dev_write_t
79may block.
80On success, the number of bytes written is returned.
81On error, -1 is returned.
82.El
83.Pp
84When calling
85.Fn fido_dev_set_io_functions ,
86the
87.Fa open ,
88.Fa close ,
89.Fa read ,
90and
91.Fa write
92fields of
93.Fa io
94may not be NULL.
95.Pp
96No references to
97.Fa io
98are held by
99.Fn fido_dev_set_io_functions .
100.Pp
101The
102.Fn fido_dev_set_sigmask
103function may be used to specify a non-NULL signal mask
104.Fa sigmask
105to be used while
106.Em libfido2's
107default I/O handlers wait on
108.Fa dev .
109On UNIX-like operating systems,
110.Vt fido_sigset_t
111is defined as
112.Vt sigset_t .
113On Windows,
114.Vt fido_sigset_t
115is defined as
116.Vt int
117and
118.Fn fido_dev_set_sigmask
119is a no-op.
120.Pp
121No references to
122.Fa sigmask
123are held by
124.Fn fido_dev_set_sigmask .
125.Sh RETURN VALUES
126On success,
127.Fn fido_dev_set_io_functions
128and
129.Fn fido_dev_set_sigmask
130return
131.Dv FIDO_OK .
132On error, a different error code defined in
133.In fido/err.h
134is returned.
135