'\"macro stdmacro
.if n .pH g3c.fattach @(#)fattach	40.6 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} fattach 3C "" "\&"
.if \nX=1 .ds x} fattach 3C ""
.if \nX=2 .ds x} fattach 3C "" "\&"
.if \nX=3 .ds x} fattach "" "" "\&"
.TH \*(x}
.SH NAME
\f4fattach\fP \- attach a \s-1STREAMS\s+1-based file descriptor to an object 
in the file system name space
.SH SYNOPSIS
.nf
\f4int fattach(int fildes, const char *path);\f1
.fi
.SH DESCRIPTION
The \f4fattach\f1 routine attaches a \s-1STREAMS\s+1-based file descriptor to an
object in the file system name space, effectively associating a name with
\f2fildes\f1.
\f2fildes\f1 must be a valid open file descriptor representing a \s-1STREAMS\s+1 file.
\f2path\f1 is a path name of an existing object and the user must have
appropriate privileges or be the owner of the file and have write permissions.
All subsequent operations on \f2path\f1 will operate on the
\s-1STREAMS\s+1 file until the \s-1STREAMS\s+1 file is detached from the node.
\f2fildes\f1 can be attached to more than one \f2path\f1, i.e., a stream can
have several names associated with it.
.PP
The attributes of the named stream [see \f4stat\f1(2)], are initialized as follows:
the permissions, user \s-1ID\s0, group \s-1ID\s0, and times are set to those of
\f2path\f1, the number of links is set to 1, and the size and device
identifier are set to those of the streams device associated with \f2fildes\f1.
If any attributes of the named stream are subsequently changed 
[e.g., \f4chmod\f1(2)], the attributes of the underlying object are
not affected.
.SH "RETURN VALUE"
If successful, \f4fattach\f1 returns 0; otherwise it returns -1 and sets 
\f4errno\f1 to indicate an error.
.SH ERRORS
Under the following conditions,
the function \f4fattach\f1 fails and sets \f4errno\f1 to:
.TP 13
\f4EACCES\fP
The user is the owner of \f2path\f1 but does not have write
permissions on \f2path\f1 or \f2fildes\f1 is locked.
.TP 13
\f4EBADF\fP
\f2fildes\f1 is not a valid open file descriptor.
.TP 13
\f4ENOENT\fP
\f2path\f1 does not exist.
.TP 13
\f4ENOTDIR\fP
A component of a path prefix is not a directory.
.TP 13
\f4EINVAL\fP
\f2fildes\f1 does not represent a \s-1STREAMS\s+1 file.
.TP 13
\f4EPERM\fP
The effective user \s-1ID\s0 is not the owner of \f2path\f1 or a user with
the appropriate privileges.
.TP 13
\f4EBUSY\fP
\f2path\f1 is currently a mount point or has a \s-1STREAMS\s+1 file
descriptor attached it.
.TP 13
\f4ENAMETOOLONG\fP
The size of \f2path\f1 exceeds \f4{PATH_MAX}\fP, or the component of 
a path name is longer than \f4{NAME_MAX}\fP while \f4{_POSIX_NO_TRUNC}\fP 
is in effect.
.TP 13
\f4ELOOP\fP
Too many symbolic links were encountered in translating \f2path\f1.
.TP 13
\f4EREMOTE\fP
\f2path\fP is a file in a remotely mounted directory.
.SH "SEE ALSO"
\f4fdetach\f1(1M),\f4fdetach\fP(3C), \f4isastream\fP(3C), \f4streamio\fP(7)
.br
in the \f2Programmer's Guide: \s-1STREAMS\s+1\fP
.Ee
