fattach(3)fattach(3)NAMEfattach - Attach a STREAMS-based file descriptor to a file in the file
system name space
SYNOPSIS
#include <stropts.h>
int fattach(
int fd,
const char *path );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
fattach(): XSH4.0, XSH4.2, XSH5.0
Refer to standards(5) for more information about industry standards and
associated tags.
PARAMETERS
Specifies a valid open file descriptor that is associated with a
STREAMS file. Specifies the pathname of an existing regular file or
directory.
DESCRIPTION
The fattach() function associates a STREAMS-based file descriptor to
the file pointed to by the path parameter.
A successful call to the fattach() function causes all pathnames that
name the file named by the path parameter to name the STREAMS file
associated with the fd parameter until the STREAMS file is detached
from the file. The STREAMS file is detached from the file by using the
fdetach() function. A STREAMS file can be attached to more than one
file and can have several pathnames associated with it.
The attributes of the named STREAMS file are initialized as follows:
The group ID, user ID, times, and permissions are set to those of the
file pointed to by the path parameter. The number of links is set to
1. The size and the device identifier are set to those of the STREAMS
file that is associated with the fd parameter.
If any of the attributes of the named STREAMS file are subsequently
changed, for example by the chmod() function, the change affects nei‐
ther the attributes of the underlying file nor the attributes of the
STREAMS file to which the fd parameter refers.
Any file descriptors referring to the underlying file that were opened
prior to an fattach() call continue to refer to the underlying file.
The fattach() function uses the File-on-File Mounting (FFM) file sys‐
tem. Instead of mounting a file system on a mount point, the fattach()
function ffm mounts a file descriptor on a mount point, which can be
either a directory or a regular file. See ffm(4).
RESTRICTIONS
[Tru64 UNIX] The fattach() function requires that the FFM_FS kernel
option be configured. See System Administration for information on
configuring kernel options.
RETURN VALUES
Upon successful completion, the fattach() function returns a value of 0
(zero). Otherwise, it returns a value of -1, and errno is set to indi‐
cate the error.
ERRORS
If any of the following conditions occurs, the fattach() function sets
errno to the value that corresponds to the condition.
Although the user is the owner of path, the user has no write permis‐
sions for it, or the object designated by fd is locked. The fd parame‐
ter is an invalid file descriptor. The existing object specified by
the path parameter is already mounted or has a STREAMS file descriptor
attached to it. [Tru64 UNIX] The path parameter points to a location
outside of the allocated address space of the process. The fd parame‐
ter refers to a socket and not a STREAMS file.
[Tru64 UNIX] The superblock for the file system had an incor‐
rect magic number or an out of range block size.
[Tru64 UNIX] The pathname is incorrect. When path was trans‐
lated, too many symbolic links were found. [Tru64 UNIX] There
are too many file descriptors attached (system-wide). An ele‐
ment of the path parameter does not exist or is an empty string.
[Tru64 UNIX] The system resources have been exhausted. The
directory portion of the path parameter does not exist. [Tru64
UNIX] The size of a pathname component is longer than NAME_MAX
when _POSIX_NO_TRUNC is in effect.
The pathname length is longer than PATH_MAX or the length of the
intermediate result of a pathname resolution of a symbolic link
is longer than PATH_MAX. The current effective user ID is not
the owner of the existing file specified by the path parameter.
Another cause of the error is if the current effective user ID
does not specify a user with the correct privileges. A link to
a file on another file system has been attempted.
EXAMPLES
The following example shows a program that attaches a STREAMS file to a
regular file and results in a df display that indicates the File-on-
File Mounting (FFM) is the mounted file system.
#include <fcntl.h> #include <sys/stat.h> #include <sys/types.h>
#include <stropts.h> #include <stdio.h> #include <errno.h> #include
<unistd.h>
main (int argc, char **argv) {
int fd;
int error;
if ((fd = open("/tmp/astream", O_RDONLY, 0)) == -1) {
perror ("open");
exit(error);
}
printf("opened\n");
if ((error = isastream(fd)) != 1) {
printf("not a stream\n"); if (error ==
-1)
perror("isastream");
exit(-1);
}
printf("is a stream\n");
if ((error = fattach(fd, "/tmp/afile")) == -1) {
perror ("fattach");
exit(error);
}
printf("fattached\n");
exit(0); }
% df /tmp/afile Filesystem 512-blocks Used Available Capacity
Mounted on file-on-file mount 0 0 0 100%
/tmp/afile
SEE ALSO
Functions: fdetach(3), isastream(3), chmod(2), stat(2), mount(2)
Commands: fdetach(8)
Interfaces: streamio(7)
Files: ffm(4)
Standards: standards(5)
Network Programmer's Guide
fattach(3)