lib/librt/mq_unlink.2

   1 .\"     $NetBSD: mq_unlink.3,v 1.1 2009/01/05 21:19:49 rmind Exp $
   2 .\"
   3 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   4 .\"
   5 .Dd August 19, 2009
   6 .Dt MQ_UNLINK 2
   7 .Os
   8 .Sh NAME
   9 .Nm mq_unlink
  10 .Nd remove a message queue (REALTIME)
  11 .Sh LIBRARY
  12 .Lb librt
  13 .Sh SYNOPSIS
  14 .In mqueue.h
  15 .Ft int
  16 .Fn mq_unlink "const char *name"
  17 .Sh DESCRIPTION
  18 The
  19 .Fn mq_unlink
  20 function removes the message queue named by the pathname
  21 .Fa name .
  22 After a successful call to
  23 .Fn mq_unlink
  24 with
  25 .Fa name ,
  26 a call to
  27 .Xr mq_open 2
  28 with
  29 .Fa name
  30 fails if the flag
  31 .Dv O_CREAT
  32 is not set in
  33 .Fa flags .
  34 If one or more processes have the message queue open when
  35 .Fn mq_unlink
  36 is called, destruction of the message queue will be postponed until
  37 all references to the message queue have been closed.
  38 .Pp
  39 Calls to
  40 .Xr mq_open 2
  41 to recreate the message queue may fail until the message queue is
  42 actually removed.
  43 However, the
  44 .Fn mq_unlink
  45 call need not block until all references have been closed;
  46 it may return immediately.
  47 .Sh RETURN VALUES
  48 Upon successful completion, the function returns a value of zero.
  49 Otherwise, the named message queue will be unchanged by this function call,
  50 and the function returns a value of \-1 and sets the global variable
  51 .Va errno
  52 to indicate the error.
  53 .Sh ERRORS
  54 The
  55 .Fn mq_unlink
  56 function fails if:
  57 .Bl -tag -width Er
  58 .It Bq Er EACCES
  59 Permission is denied to unlink the named message queue.
  60 .It Bq Er ENAMETOOLONG
  61 The length of the name argument exceeds
  62 .Brq Dv PATH_MAX
  63 or a pathname
  64 component is longer than
  65 .Brq Dv NAME_MAX .
  66 .It Bq Er ENOENT
  67 The named message queue does not exist.
  68 .El
  69 .Sh SEE ALSO
  70 .Xr mq_close 2 ,
  71 .Xr mq_getattr 2 ,
  72 .Xr mq_notify 2 ,
  73 .Xr mq_open 2 ,
  74 .Xr mq_receive 2 ,
  75 .Xr mq_send 2 ,
  76 .Xr mq_setattr 2
  77 .Sh STANDARDS
  78 This function conforms to the
  79 .St -p1003.1-2001
  80 standard.
  81 .Sh HISTORY
  82 The
  83 .Fn mq_unlink
  84 function first appeared in
  85 .Dx 2.5 .
  86 .Sh COPYRIGHT
  87 Portions of this text are reprinted and reproduced in electronic form
  88 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
  89 -- Portable Operating System Interface (POSIX), The Open Group Base
  90 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
  91 Electrical and Electronics Engineers, Inc and The Open Group.
  92 In the
  93 event of any discrepancy between this version and the original IEEE and
  94 The Open Group Standard, the original IEEE and The Open Group Standard
  95 is the referee document.
  96 The original Standard can be obtained online at
  97 http://www.opengroup.org/unix/online.html .