path: root/bus_create.3

.TH BUS_CREATE 3 BUS
.SH NAME
bus_create - Create a new bus
.SH SYNOPSIS
.LP
.nf
#include <bus.h>
.P
int bus_create(const char *\fIfile\fP, int \fIflags\fP, char **\fIout_file\fP);
.fi
.SH DESCRIPTION
The
.BR bus_create ()
function creates a bus with the asscoiated pathname specifed by the
value of the parameter \fIfile\fP.  If \fIfile\fP is \fINULL\fP a random
pathname is selected.  This pathname adheres to the convention set forth
by
.BR bus (5).
.PP
If \fIfile\fP is not \fINULL\fP the
.BR bus_create ()
function fails if the file already exists if \fIflags\fP contains
\fIBUS_EXCL\fP.  Otherwise if \fIfile\fP is not \fINULL\fP, the
.BR bus_create ()
function does nothing if the file already exists.
.PP
If \fIflags\fP contains \fIBUS_INTR\fP, the function fails if it is
interrupted.
.PP
Unless \fIout_file\fP is \fINULL\fP, the pathname of the bus should be
stored in a new char array stored in \fI*out_file\fP.  The caller must
free the allocated stored in \fI*out_file\fP.
.SH RETURN VALUES
Upon successful completion, the function returns 0.  Otherwise the
function return -1 with \fIerrno\fP set to indicate the error.
.SH ERRORS
.TP
.B ENOMEM
The process cannot allocate more memory.
.PP
The
.BR bus_create (3)
function may also fail and set \fIerrno\fP to any
of the errors specified for the routines
.BR open (2)
and
.BR write (2).
.SH SEE ALSO
.BR bus-create (1),
.BR bus (5),
.BR libbus (7),
.BR bus_unlink (3),
.BR bus_open (3),
.BR open (2),
.BR write (2)